search-copilot-chats

name	search-copilot-chats
description	Search across archived Copilot chat sessions (VS Code + CLI) using the copilot-session-tools CLI. Use when the user says "search my chats", "find in chat history", "what did we discuss about X", "look up past sessions", "scan chats", "session history", "recent session where", "earlier conversation", "previous session", "that session where", or references a session-state path or session GUID. Also covers exporting sessions as markdown or HTML and launching the web viewer. Use when this capability is needed.
metadata	{"author":"arithmomaniac"}

Search Copilot Chats

Search, browse, and export archived GitHub Copilot chat sessions from VS Code (Stable & Insiders) and the Copilot CLI. Uses the copilot-session-tools CLI backed by a local SQLite database with FTS5 full-text search. Requires Copilot CLI v0.0.412+ (uv tool install copilot-session-tools[all] if not on PATH).

Do not memorize flags. Run copilot-session-tools <command> --help for flags and examples. This skill only documents domain knowledge that --help cannot teach.

When to use

• User asks to search past Copilot conversations ("what did we discuss about X?")
• User pastes a session-state path or session GUID and wants context from it
• User pastes a web viewer URL like http://127.0.0.1:5000/session/{uuid}
• User wants to find prior decisions, code patterns, or troubleshooting steps from past sessions
• User asks to export a session as markdown, HTML, or JSON

Favor CLI over Python

Always prefer CLI execution over writing Python scripts. The CLI handles all common workflows. Only drop into Python/SQL when you need a custom join, aggregation, or programmatic processing the CLI doesn't support.

Search strategy (critical — not in --help)

The FTS5 search uses AND semantics: every keyword in the query MUST appear in the same message. More keywords = stricter matching = fewer results. This is the #1 cause of empty search results.

Start broad, narrow later. Always begin with 1–2 core keywords. Only add more if you get too many results.

Iterative approach. If no results are returned, remove keywords (don't add more). Try synonyms. Drop field filters. The goal is to widen the net, not narrow it further.

Field filters don't reduce keyword strictness. A filter like workspace:ZTS narrows the session pool, but all FTS keywords still must match within a single message.

Keyword budget. Aim for 2–3 keywords max. Use exact phrases for multi-word concepts (e.g., "resource graph" counts as 1 match unit).

Search dos and don'ts

❌ DON'T — these all returned zero results in real usage:

Failed query	Problem
customer tenant query build SPN	5 loose keywords — ALL must appear in one message
workspace:ZTS "resource graph" integration test permission	Workspace filter + exact phrase + 3 keywords = too strict
"build service" "resource graph" reader	Two exact phrases + a keyword — very unlikely all in one message
spec driven proposal specs design tasks	6 keywords, too many AND conditions

✅ DO — these succeeded:

Successful query	Why it works
ARG build pipeline	3 focused keywords
"resource graph" auth	1 exact phrase + 1 keyword
workspace:ZTS ARG RBAC	Workspace filter + only 2 keywords
docker build	2 keywords, broad

Iterative search workflow:

Step 1: copilot-session-tools search "resource graph" --full --limit 20
  → Too many results? Add ONE keyword:
Step 2: copilot-session-tools search "resource graph" auth --full --limit 20
  → Still too many? Add a workspace filter:
Step 3: copilot-session-tools search 'workspace:ZTS "resource graph" auth' --full --limit 10
  → No results? Back up and try different keyword:
Step 4: copilot-session-tools search 'workspace:ZTS "resource graph" permission' --full --limit 10

Extract session references from user input

Users reference past sessions in several ways. Recognize and extract the session GUID:

User provides	Extract
C:\Users\...\session-state\{uuid} or ~\.copilot\session-state\{uuid}	The {uuid} portion
http://127.0.0.1:5000/session/{uuid}	The {uuid} portion
A bare GUID like 67894303-8571-...	Use directly as session ID
A short prefix like 67894303	Search: copilot-session-tools search "67894303"

Then use export-markdown --session-id to retrieve the full session content.

Direct SQL for advanced queries

When the CLI search doesn't support your query shape, use SQLite directly on ~/.copilot/session-store.db:

# Find sessions by workspace name
sqlite3 "$HOME/.copilot/session-store.db" "SELECT session_id, workspace_name, created_at FROM cst_sessions WHERE workspace_name LIKE '%zts%' ORDER BY created_at DESC LIMIT 20"

# Count messages per session (find long conversations)
sqlite3 "$HOME/.copilot/session-store.db" "SELECT s.session_id, s.workspace_name, COUNT(m.id) as msg_count FROM cst_sessions s JOIN cst_messages m ON s.session_id = m.session_id GROUP BY s.session_id ORDER BY msg_count DESC LIMIT 20"

# Find sessions with tool invocations of a specific tool
sqlite3 "$HOME/.copilot/session-store.db" "SELECT DISTINCT s.session_id, s.workspace_name, s.created_at FROM cst_sessions s JOIN cst_messages m ON s.session_id = m.session_id JOIN cst_tool_invocations ti ON m.id = ti.message_id WHERE ti.name LIKE '%build%' ORDER BY s.created_at DESC LIMIT 20"

# Find file changes by path pattern
sqlite3 "$HOME/.copilot/session-store.db" "SELECT DISTINCT s.session_id, s.workspace_name, fc.path FROM cst_sessions s JOIN cst_messages m ON s.session_id = m.session_id JOIN cst_file_changes fc ON m.id = fc.message_id WHERE fc.path LIKE '%Dockerfile%' ORDER BY s.created_at DESC LIMIT 20"

Database schema (quick reference)

The tool extends ~/.copilot/session-store.db with cst_* enrichment tables. Built-in tables are never modified.

Built-in tables (managed by Copilot CLI, read-only):

Table	Key columns
sessions	id, cwd, repository, branch, summary, created_at
turns	session_id, turn_index, user_message, assistant_response

Enrichment tables (managed by this tool, prefixed cst_):

Table	Key columns
cst_sessions	session_id, workspace_name, vscode_edition, custom_title, parser_version, source_format
cst_messages	session_id, message_index, role, content, timestamp
cst_messages_fts	content (FTS5 virtual table, synced via triggers)
cst_tool_invocations	message_id, name, input, result, status
cst_file_changes	message_id, path, diff, content
cst_command_runs	message_id, command, result, status, output

Workflow: "Continue where we left off"

1. Extract the session GUID from the user's input (see table above)
2. Export: copilot-session-tools export-markdown --session-id <guid> -o .
3. Read the exported file and continue the work

Workflow: "Find how we solved X before"

1. Search: copilot-session-tools search "<topic>" --full --limit 30
2. Identify the most relevant session from results
3. Export: copilot-session-tools export-markdown --session-id <guid> -o .

Known issues

• Use --json for piped output. The default Rich console output garbles Unicode box-drawing characters on Windows when piped. --json bypasses Rich entirely and is the preferred format for programmatic consumption.
• Missing sessions: If a session doesn't appear after scanning, check that the source file exists and wasn't cleaned up by VS Code. Use --full scan to force reimport.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.