← GameCopilot

GameCopilot — User Guide

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.

Table of contents

• 1. Installation and launch
• 2. The OpenRouter key and choosing a model
• Choosing the chat model (Model ID)
• The embedding model (for RAG and search)
• 3. First run — setup wizard
• Linking to a game
• 4. Overlay: the control bar
• 5. Chat
• Built-in browser
• Chat sidebar 📚
• 6. Chat search (🔍)
• 7. RAG — per-game memory (🧠 in the composer)
• 8. Notes 📝 and the progress journal 🧭
• 9. Games library (Settings → Library)
• 10. Hotkeys, tray, and running in the background
• 11. Prompts: the prompts folder
• Your own communication style in a minute
• System prompts: what does what
• Rules and substitutions
• 12. Settings (⚙)
• 13. Where your data lives
• 14. Troubleshooting

1. Installation and launch

Requirements:

• Windows 10/11;
• an internet connection;
• an OpenRouter account with an API key and credit balance (see section 2).

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".

2. The OpenRouter key and choosing a model

GameCopilot works through OpenRouter — a single API gateway to hundreds of models (Google, OpenAI, Anthropic, and others). It is the only provider the app needs.

Getting a key:

1. Sign up at openrouter.ai.
2. Top up your balance at openrouter.ai/credits — a few dollars go a long way; a typical question with an answer costs a fraction of a cent.
3. Create a key at openrouter.ai/keys (it starts with sk-or-v1-…) 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.

Choosing the chat model (Model ID)

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:

• Multimodality is mandatory. The model must accept images as input (catalog filter Input modalities → Image): chat screenshots and the progress scanner depend on it. GameCopilot validates this at startup and on settings save — with a text-only model the app simply won't start and will show "Model unavailable / does not accept images".
• Speed beats raw power. You need the assistant right now, without alt-tabbing out of the game — light, fast models (…-flash, …-mini) are nearly as good as flagships on gaming questions while answering several times faster and cheaper.
• Price. The catalog lists each model's cost per million tokens. Keep in mind every screenshot adds hundreds to thousands of tokens to a request, and web search (:online) adds a small per-call surcharge.
• Knowledge cutoff barely matters — freshness comes from the built-in web search: GameCopilot appends OpenRouter's :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:

The embedding model (for RAG and search)

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.

3. First run — setup wizard

On first launch a three-step wizard opens:

1. OpenRouter API key — paste your key (section 2).
2. Model ID — a multimodal model identifier (section 2).
3. Style and appearance — communication style (see section 11), theme (light/dark; light by default), font and size.

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).

Linking to a game

After picking a window, GameCopilot asks what to do:

• Link to game …? — attach to an existing game entry (when the executable is known);
• Create a game entry …? — create a new game: chats, notes, and progress will be saved;
• decline both — 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.

4. Overlay: the control bar

The window's top bar (left to right):

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).

5. Chat

The bottom row is the composer: the "Message…" field, 🖼, 🧠, Send, 🔄.

• Ask a question — type and press Enter or Send. The answer streams into the assistant bubble with markdown rendering: bold/italic, lists, tables, blockquotes, strikethrough, and clickable links. The chat auto-scrolls to follow the growing answer; scroll up and it lets go, return to the bottom (or send a message) and it re-engages. An opened chat lands on the latest messages.
• Stop — while an answer streams, the Send button becomes Stop: clicking it aborts the generation (the question is kept, the partial answer is marked "(stopped)").
• Game screenshot 🖼 — instantly captures the game window and attaches the frame to your next message (a preview chip appears, with ✕ to remove it).
• PrintScreen / Alt+PrtSc / Win+Shift+S — any screenshot landing in the clipboard automatically becomes an attachment chip. Use this to attach a region of the screen.
• Previews in history — message images are persisted; clicking a thumbnail opens a full-size viewer (close with Esc).
• Sources — the model searches the web (when Web search is enabled in Settings); a line of clickable source domains appears under the answer. Raw URLs are kept out of the answer text.
• Links — clicking a link in an answer, the sources line, notes, or the journal opens it in the built-in browser (see below).
• 🔄 Reset context — clears the current conversation context (the model "forgets" the exchange); the history stays in the database.
• Answer language is set by the Answer language field in Settings (default Russian) — the UI itself stays English.

Built-in browser

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.

• One window per link: clicking the same link again closes its window (a toggle); clicking a different link opens a new window next to it.
• Turn it off with the Open links in built-in browser checkbox in Settings — links then go to the system browser.
• If the WebEngine component is unavailable in the build, the checkbox is disabled and links automatically open in the system browser.

Chat sidebar 📚

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.

6. Chat search (🔍)

The 🔍 button in the sidebar opens a search window over the entire chat history of the game currently selected in the sidebar:

Two modes:

• Keyword (default). Full-text search (FTS5) as you type — from 2 characters, instant, across all messages and chat titles. Matches are bolded in the snippets; rows with the 💬 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.

7. RAG — per-game memory (🧠 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).

• The 🧠 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).
• Button states: active (index ready) · "Building index…" (indexing in progress — wait) · "No indexed data yet" (nothing to retrieve for this game) · disabled while browsing another game.
• A footer appears under the answer, e.g. "RAG: 3 fragments (notes ×2, history ×1)" — how many fragments of which kinds were fed into the context. "RAG: no context found" means retrieval ran but found nothing relevant.
• Which kinds of data participate in retrieval is configured per game in the library: the chats / notes / progress / meta flags (section 9).
• Every new chat opens with an index-status banner — "Index: ready — 40 chat messages, 12 progress entries, notes…" or the short "Index: ready (57 items)". The format is switched by the Detailed index status checkbox in the tray menu or in Settings.
• The model is explicitly forbidden from inventing facts "from your notes": if the answer isn't in the context, it must say so (the text of this rule lives in prompts/system/rag_header.txt and can be edited).

8. Notes 📝 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.

• Scan now — an on-demand scan right away;
• ✖ on an entry — delete it; Clear all — wipe the journal (with confirmation);
• the status line shows "Scanner: on — next scan in ~N min", "off for this game", and the last error if any;
• the journal keeps at most Progress entries per game records (200 by default); older ones are deleted together with their images.

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.

9. Games library (Settings → Library)

For each game:

• Meta… / Rebuild — view and rebuild the meta (the model re-researches the game online; after a rebuild the progress summary is rewritten against the new meta);
• RAG flags chats / notes / progress / meta — which of the game's data participates in context retrieval;
• scan — enable the scanner for this game;
• Rename — rename; Sources… — set "trusted" source sites (passed to the model as recommended search targets);
• Merge into… — merge duplicates: chats/notes/progress move to the target game, the index rebuilds automatically (a banner reports when it's ready), and the target's meta is cleared — rebuild it. The "Possible duplicates" badge hints when two entries look alike;
• Delete — delete the game with all its chats, notes, and journal.

10. Hotkeys, tray, and running in the background

Global hotkeys (work even while the game has focus; configurable in Settings, an empty field = disabled):

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 three-item menu: Show / Hide, the Detailed index status checkbox (verbose or short index banner in a new chat, section 7), 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.

11. Prompts: the prompts folder

Every 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

Your own communication style in a minute

A style is a short "how to answer" instruction injected into every chat's system prompt. To add your own:

1. Create styles\<name>.txt — e.g. styles\coach.txt with: "Answer like a strict esports coach: dissect mistakes, prescribe concrete drills, no consolations."
2. Restart GameCopilot.
3. Pick 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.

System prompts: what does what

• 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.

Rules and substitutions

• Files are read once at startup. No hot reload: edit → restart the app.
• You can't break it. A template error (a typo in a {placeholder}) never crashes the app: a warning goes to the log and the built-in text is used instead.
• Placeholders {name} may be moved or removed, but not renamed:

Warning: in scan.txt the 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).

12. Settings (⚙)

Save validates the model and persists everything at once. Clicking ⚙ again closes the window without saving.

13. Where your data lives

%APPDATA%\GameCopilot\:

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.

14. Troubleshooting

Screenshots in docs/img/ are rendered by scripts/render_docs_shots.py (demo data). Document version: 0.4 (July 2026), matches GameCopilot 0.5.6.