GameCopilot is a game assistant overlay for Windows. A compact panel with a chat floats above your game window: you ask a question (optionally with a game screenshot), and a multimodal model via OpenRouter searches current sources (wikis, guides, patch notes) and answers in your language. The app keeps per-game chat history with full-text and semantic search, stores your notes, periodically scans the screen to maintain a progress journal, and feeds the accumulated knowledge back into answers via RAG.
Requirements:
Running the .exe: the build folder dist\GameCopilot\ is fully portable — copy it anywhere and run GameCopilot.exe. No installation needed.
Running from sources (alternative):
C:/GameCopilot/.venv/Scripts/python.exe -m gamecopilot.app
All data is stored in %APPDATA%\GameCopilot (see section 13), so the .exe and a from-source run share the same settings, chats, and notes.
Single instance. Launching GameCopilot again does not start a second process — it simply shows and raises the already-running window. If the overlay "disappeared" (hidden by a hotkey), the easiest way to get it back is to run the exe again or click the tray icon (section 10).
Limitation: the overlay works on top of games in windowed and borderless mode. Exclusive fullscreen is not supported — switch the game to "borderless windowed".
To make the assistant work you need one of two ways to pay for model requests — switch between them any time in Settings → API access (the same choice appears on step 1 of the first-run wizard):
The payment method doesn't affect which model you use (section 2.3) — the Model ID field works the same either way.
Coins are GameCopilot's own currency at a fixed rate: 1 coin = $1 of model usage (charged at the actual OpenRouter cost of each request, web search and screenshots included).
Buying in the app:
You can top up again any time the same way: Settings → Buy coins…, the tray menu (right-click the tray icon → Buy coins…, shown only in coins mode), or automatically — if you run out mid-session, the purchase window pops up on its own over the overlay.
If you bought coins somewhere other than in the app (e.g. from a store page on itch.io) or you're reinstalling GameCopilot on another PC, access is restored with a license key instead:
Lost the e-mail, or need the key on a second PC? Log in to the Polar customer portal at polar.sh with the e-mail you paid with — every license key tied to your purchases is listed there, retrievable any time, no support ticket needed.
GameCopilot can also work directly through OpenRouter — a single API gateway to hundreds of models (Google, OpenAI, Anthropic, and others) — if you'd rather pay it directly and manage your own balance.
Getting a key:
sk-or-v1-…), then in Settings → API access pick "I have my own OpenRouter API key" and paste it into the first-run wizard or Settings.The key is stored only in the Windows Credential Manager (service GameCopilot) — it is never written to config files.
The model identifier is entered manually — exactly as it appears in the openrouter.ai/models catalog (e.g. google/gemini-2.5-flash). What to look for:
…-flash, …-mini) are nearly as good as flagships on gaming questions while answering several times faster and cheaper.:online) adds a small per-call surcharge.:online suffix to the model, feeding it search results from current wikis and guides. Works with any model; toggled by the Web search checkbox.Proven options:
| Model | Notes |
|---|---|
google/gemini-2.5-flash |
A sensible default: fast, cheap, good vision — the app was developed against it |
google/gemini-2.5-pro |
Smarter and noticeably pricier/slower — for heavy theorycrafting questions |
openai/gpt-5-mini |
OpenAI's fast multimodal, comparable to flash |
anthropic/claude-sonnet-5 |
Strong reasoning and careful answers, mid-range price |
A separate, "invisible" model turns text into vectors for RAG (section 7) and semantic search (section 6). Default is google/gemini-embedding-2; alternatives: openai/text-embedding-3-small, openai/text-embedding-3-large, qwen/qwen3-embedding-8b, baai/bge-m3. Embeddings cost pennies even with heavy use. Don't change the model without a reason: switching drops the vector index, which then rebuilds in the background from scratch.
On first launch a three-step wizard opens:
After the wizard (and on every subsequent launch) the app validates the model and asks you to pick the game window:
Open the game beforehand, click Refresh, select the window, and click Pick. The window is remembered by its handle; if the game closes, the overlay says "Target window closed — pick it again" — you can re-pick from Settings (Target window → Pick window).
After picking a window, an attach dialog opens — one list instead of a chain of questions:
Enter = link); handy when the same game is launched via different launchers/executables;Esc) — a sessionless mode: you can chat, but nothing is written to the database (the header shows a banner; notes and history are unavailable).When creating a game you are offered to build the game meta right away ("Build game meta now?") — the model researches the game online and produces a short brief (genre, current patch, notable changes). Meta improves the scanner and RAG; you can build/rebuild it later from the games library.
The window's top bar (left to right):
| Button | Action |
|---|---|
⠿ |
Drag the window (hold and move). The window snaps to screen edges and center |
| — | Current game name |
🛡 |
Spoiler shield for the active game (section 7): highlighted — on, click to toggle. Visible only during an active, saved session |
| gray text | Hint with the current show/hide hotkey (Ctrl+- Show or hide widget); disappears when the hotkey is disabled |
📚 |
Sidebar with chat history and search |
👁 |
Opacity: toggles between normal (85 %) and "ghost" (35 %); both values are configurable |
📝 |
Game notes |
🧭 |
Progress journal (scanner) |
📖 / 📘 |
Collapse/expand the chat into a compact pill: open book — chat expanded, closed book — collapsed |
⚙ |
Settings |
✖ |
Quit |
Collapsed view — just the button bar:
Resize the window by the grip in the bottom-right corner; position and size are remembered. Esc removes focus from the input field (handy for returning control to the game).
Open panels remember your choice: collapse the chat into a pill and the 📚 and 📝 buttons dim along with their panels; expand it again and the sidebar and notes that were open before come back on their own. A button's highlight always reflects the panel's actual state.
The bottom row is the composer: the "Message…" field, 🖼, 🧠, Send, 🔄, your OpenRouter balance, and 💲. Above the composer is a row of quick-prompt chips with a recap button ⏪ (see below).
🖼 — instantly captures the game window and attaches the frame to your next message (a preview chip appears, with ✕ to remove it).Esc).$0.0031); more on this under balance below.🔄 Reset context — clears the current conversation context (the model "forgets" the exchange); the history stays in the database.
So you don't have to alt-tab out of the game, links open in GameCopilot's own mini-browser: a window above the overlay with back/forward/reload buttons and a read-only URL bar; closes with Esc.
📚The list of the current game's chats: + New — new chat, 🔍 — chat search (section 6), ✎ — rename, 🗑 — delete. Your first question automatically becomes the chat title.
The games dropdown at the top lets you browse other games' chats read-only: while a non-active game is selected, the composer and action buttons are disabled (a "View only — read-only" badge shows). To write again, return to the active game or re-pick the window.
⏪Above the composer is a row of chips: click one to instantly send a ready-made question ("What should I do next?", "How do I beat the boss?"…); Shift+click inserts its text into the field for editing instead. A draft already sitting in the input field is not lost when you click a chip — the chip sends separately. The set of chips is yours to define: the Quick prompts… button in Settings opens an editor (columns "Chip" — the button's label, and "Message" — the text that gets sent).
The first chip is the built-in recap ⏪: one click, and the assistant reads the progress journal and the tail of your last conversation to tell you where you left off, what you accomplished, and what the next step was. Ideal after a week away. The recap is built from local data only (no web search needed, and RAG mixing is disabled for it — no extra cost) and is saved to the chat like a regular answer. The chip is disabled in a sessionless session.
💲 / 🪙On the right of the composer is your current balance, displayed differently depending on how you pay (section 2): in GameCopilot Coins mode the refresh button is 🪙 and the balance is a bare number of coins (e.g. 12.42); in your-own-OpenRouter-key mode the button is 💲 and the balance is in dollars to four decimal places (e.g. $12.4183). The balance is fetched once at startup; click the button (🪙 or 💲) to refresh it manually. If the request fails, the label shows — ($ — in key mode), and the reason is in the button's tooltip. The exact price of every answer is shown separately underneath it in the chat — computed by OpenRouter itself, including web search and screenshots; in coins mode, 1 coin = $1 spent. If you run out of coins mid-conversation, the assistant says so in chat and the purchase window (section 2.1) opens on its own.
🔍)The 🔍 button in the sidebar opens a search window over the entire chat history of the game currently selected in the sidebar:
Two modes:
💬 icon are chat-title matches.🧠 Semantic — by meaning. Flip the toggle and press Enter: the query is embedded and matched by semantic similarity rather than exact words — "how to kill the first boss" finds the Eikthyr conversation even if the word "boss" never appears in it. The relevance cutoff is configurable ("Semantic match floor", 29 % by default). Semantic mode becomes available once the game's vector index is ready (the same infrastructure RAG uses); after an app upgrade, older history finishes indexing in the background.Clicking a result opens that chat, scrolls to the matched message, and flashes it. Search also works while browsing another game — it searches whichever game is selected in the sidebar dropdown.
🧠 in the composer)RAG mixes relevant fragments of your game history into the question: past chats, notes, the progress journal, and the meta. All of it is indexed with vector embeddings (section 2).
🧠 button in the composer enables RAG for the current chat (you can enable it even before the first message — the intent applies to the chat about to be created).chats / notes / progress / meta flags (section 9).prompts/system/rag_header.txt and can be edited).🛡The flip side of memory: since the assistant knows where you are, it can also avoid running ahead. Turn the shield on — with the 🛡 button next to the game name, or the "🛡 no spoilers" checkbox in the library — and the model gets a hard rule: the progress journal and notes mark your "frontier," and anything further along the story (bosses, locations, plot twists, late-game content) stays unrevealed. Hints come in steps — a nudge first, the full answer only on request, and before an unavoidable spoiler the assistant warns you and asks to confirm.
The shield is a per-game flag: turn it on for a story-driven RPG, off for a sandbox. The more carefully you keep the progress journal (section 8), the more precisely the model knows what you already know. The rule's text is editable like any other prompt: prompts/system/spoiler_shield.txt (section 11).
📝 and the progress journal 🧭Notes — one markdown document per game, shown under the composer. Click the text (or ✏️) to switch view ↔ edit — the ✏️ button stays highlighted while editing; saving is automatic (debounced, and on quit). Dragging the separator above the panel sets its height directly (remembered; at most a third of the window's height, recomputed as you resize it); double-click the separator to return to the automatic mode — the panel hugs the note, capped at the same third of the window. Long notes scroll inside; links in notes are clickable (they open in the built-in browser), while a click outside a link opens the editor. Notes are indexed for RAG by headings and paragraphs — structure them with markdown headings for more precise retrieval.
Progress journal — the 🧭 window:
If the scanner is enabled for the game (the scan flag in the library; off by default), GameCopilot captures a game frame every N minutes (the Scan interval setting); the model describes what's happening and updates the progress summary (the line under the title, grounded in the game meta). Each journal entry is a frame thumbnail + description + timestamp.
✖ on an entry — delete it; Clear all — wipe the journal (with confirmation);The progress summary is rendered as markdown — links in it open in the built-in browser. Journal entries (with the progress flag on) also feed RAG — the assistant remembers where you've been and what you did.
For each game:
chats / notes / progress / meta — which of the game's data participates in context retrieval;🛡 button on the overlay bar;Global hotkeys (work even while the game has focus; configurable in Settings, an empty field = disabled):
| Hotkey (default) | Action |
|---|---|
Ctrl+- |
Show/hide the widget together with all its windows — Settings, library, journal, search, and built-in browsers hide and come back exactly as they were |
Ctrl+= |
Toggle opacity (same as the 👁 button) |
Ctrl+0 |
Collapse/expand the chat (same as the 📖 button) |
The current show/hide hotkey is always visible as the gray hint in the top bar. When shown via hotkey, the overlay appears on the monitor of the currently focused window — handy on multi-monitor setups. If the system refuses to register a hotkey (another app grabbed it), a chat banner suggests rebinding it in Settings.
System tray. GameCopilot has a tray icon: left-click shows/hides the overlay; right-click opens a menu: Show / Hide, the Detailed index status checkbox (verbose or short index banner in a new chat, section 7), a Buy coins… item (shown only in coins mode, section 2.1 — opens the purchase window without going into Settings), and Quit. An overlay hidden by hotkey is always reachable through the tray.
Important — about "closing": Ctrl+- and the tray only hide the windows; the process keeps running (the scanner too). A full exit is the ✖ button on the bar or Quit in the tray menu. Launching the exe again while the process is running doesn't spawn a duplicate — it shows the existing window. After updating the build, quit the old process via Quit first — otherwise you'll get the old exe's window, not the new one.
prompts folderEvery prompt the app uses to talk to the model is a plain text file under
%APPDATA%\GameCopilot\prompts\. No code involved — open them in Notepad and make them yours.
%APPDATA%\GameCopilot\prompts\
├── styles\ ← communication styles (the Style dropdown items)
│ ├── minimal.txt ← essential facts only, minimal words
│ ├── beginner.txt ← newcomer-friendly, avoids extra spoilers
│ ├── pro.txt ← dense and technical: builds, routes, optima
│ └── narrative.txt ← answers in the game's own tone and lore
└── system\ ← system prompts
├── chat_base.txt ← the chat system-prompt scaffold
├── scan.txt ← the frame-scanner prompt
├── meta.txt ← the game-research (meta) prompt
├── reassess.txt ← progress-summary rewrite after a new meta
├── rag_header.txt ← the instruction header above RAG context
└── spoiler_shield.txt ← the spoiler-shield rule (added when 🛡 is on)
A style is a short "how to answer" instruction injected into every chat's system prompt. To add your own:
styles\<name>.txt — e.g. styles\coach.txt with: "Answer like a strict esports coach: dissect mistakes, prescribe concrete drills, no consolations."coach in the Style dropdown (Settings or the wizard).The file name becomes the style's name and is also passed to the model along with the text (as "coach — Answer like…"), so name the file meaningfully — even an empty style file still tells the model its name. Built-in styles can be freely edited or deleted — deleted ones do not "resurrect" on the next launch.
chat_base.txt — the main scaffold: who the model is, how to search sources, how to format answers. Edit this to change the assistant's behavior globally (e.g. "always warn about spoilers").scan.txt — the frame scanner's instruction: what to extract from a screenshot and the JSON format to reply in.meta.txt — how to research a game and what to include in the meta (genre, patch, key changes).reassess.txt — how to rewrite the progress summary after the meta is updated.rag_header.txt — the honesty rule above RAG context: answer only from the context and never attribute invented facts to the player's notes.spoiler_shield.txt — the spoiler-shield rule (section 7): don't reveal content beyond the player's progress, and give hints in steps. The file appeared in 0.6; if it's missing on disk, the built-in text is used.{placeholder}) never crashes the app: a warning goes to the log and the built-in text is used instead.{name} may be moved or removed, but not renamed:| File | Placeholders |
|---|---|
styles\*.txt |
none (plain instruction text) |
chat_base.txt |
{game_name} — game name, {style} — style ("name — text"), {language} — answer language, {sources_line} — trusted-sources line |
scan.txt |
{meta} — game meta, {progress} — current summary |
reassess.txt |
{meta}, {progress}, {observations} — recent scanner observations |
meta.txt, rag_header.txt, spoiler_shield.txt |
none |
Warning: in
scan.txtthe JSON example's curly braces are doubled ({{ }}) — that's escaping. Don't remove the second braces, or the template stops formatting (the app falls back to the built-in).
⚙)
| Field | Meaning |
|---|---|
| API access | How you pay: Buy GameCopilot coins (pack + buy button), I have a GameCopilot license key, or I have my own OpenRouter API key (section 2). The key/token is stored in Credential Manager |
| Model ID | The chat model (must be multimodal, section 2.3) |
| Embedding model | The embedding model for RAG and search. Changing it drops the index — it rebuilds in the background |
| Style | Communication style (from prompts\styles\) |
| Answer language | The model's answer language |
| Theme / Accent color / Accent text color | Light/dark theme and accent color (#RRGGBB) |
| Font / Font size | UI font and size |
| Web search | Allow the model to search the web (the :online suffix) |
| Open links in built-in browser | Open links in the built-in browser (off — system browser) |
| Detailed index status | New-chat index banner format: checked — per-kind breakdown, unchecked — one-line summary. Mirrored in the tray menu |
| Target window → Pick window | Re-pick the game window |
| Library → Games | The games library (section 9) |
| Quick prompts → Quick prompts… | Editor for quick-prompt chips (section 5): chip label + the text that gets sent, saved changes apply to the overlay immediately |
| Scan interval (min) | Scanner period, minutes |
| Embedding dimensions | Vector dimensionality (512 by default); changing it triggers a background reindex |
| Semantic match floor (%) | Relevance cutoff for semantic search and RAG (29 % by default): lower — more results, higher — stricter filtering |
| Progress entries per game | Journal record limit per game |
| Opacity (%) / Opacity faded (%) | The two opacity levels for the 👁 button |
| Hotkey: toggle widget / opacity / chat | Global hotkeys (section 10); an empty field = disabled |
Save validates the model and persists everything at once. Clicking ⚙ again closes the window without saving.
%APPDATA%\GameCopilot\:
| Path | What it is |
|---|---|
config.json |
Settings (without the API key) |
gamecopilot.db |
Database: games, chats, notes, journal, full-text and vector indexes (SQLite + FTS5 + sqlite-vec) |
history\media\<game>\*.png |
Chat and scanner screenshots |
prompts\ |
Editable prompts (section 11) |
gamecopilot.log |
Application log |
The API key is in the Windows Credential Manager (Control Panel → Credential Manager → service GameCopilot).
Full reset: close the app and delete the %APPDATA%\GameCopilot folder (and, optionally, the GameCopilot entry in Credential Manager). The next launch starts with the wizard.
| Symptom | Cause / action |
|---|---|
| A "No internet connection…" banner after startup | No network — the app starts and runs, but answers will fail until the connection is back (model validation happens in the background) |
| "Model unavailable: …" / "does not accept images" | Wrong Model ID, a model without image support (section 2), or an OpenRouter key/balance problem |
| "Target window closed — pick it again" | The game closed or the window was recreated — Settings → Pick window |
| The overlay disappeared | It's hidden by the Ctrl+- hotkey — press the hotkey again, click the tray icon, or relaunch the exe (the existing window will simply reappear) |
| Hotkeys don't work | Check the Hotkey fields in Settings (empty = disabled); if another program grabbed the combination, the app now says so with a chat banner — assign a different one |
| Updated the exe but see no new features | The old process is still running: relaunching only surfaced its window. Quit it via the tray Quit and start the exe again |
The 🧠 button is disabled |
Hover for the tooltip: "Building index…" — indexing in progress; "No indexed data yet" — no data for this game yet; RAG is also unavailable while browsing and in sessionless mode |
| Semantic search is disabled / finds little | The index is still building (after an upgrade, older history finishes indexing in the background); you can lower the "Semantic match floor" |
The balance shows $— / — |
The balance request failed — hover the label, its tooltip shows the reason (network/key); the 💲/🪙 button retries it |
| "License key not found or revoked" | Make sure the key was copied in full from the Polar e-mail; the current key is always visible in the customer portal at polar.sh (log in with your purchase e-mail) — section 2.1 |
| "Payment is still processing…" when entering a key | Polar's webhook can lag a minute or two — wait and click Save again |
| Ran out of coins mid-session | The assistant says so in chat and the coins purchase window opens automatically — top up without leaving the game (section 2.1) |
| The scanner is "silent" | Check the game's scan flag in Library and the status line in the 🧭 window — it shows the last error |
| A style/prompt didn't apply | Prompts are read at startup — restart the app; check gamecopilot.log for a broken-template warning |
| The overlay isn't visible in game | The game is in exclusive fullscreen — switch to borderless/windowed |
Support: questions or payment issues — reach out at support@digitaloutsider.xyz.
Screenshots in docs/img/ are rendered by scripts/render_docs_shots.py (demo data). Document version: 0.6 (September 2026), matches GameCopilot 0.7.0.