Search Copilot Chats

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 (copilot-session-tools) backed by a local SQLite database with FTS5 full-text search.

Installation

Install this skill for any supported AI coding agent:

# Claude Code (default)
npx skills-installer install @Arithmomaniac/copilot-session-tools/search-copilot-chats

# Other clients (Cursor, VS Code, Codex, etc.)
npx skills-installer install @Arithmomaniac/copilot-session-tools/search-copilot-chats --client cursor

For project-local installation (current directory only):

npx skills-installer install @Arithmomaniac/copilot-session-tools/search-copilot-chats --local

See claude-plugins.dev for browsing available skills.

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
• User wants to refresh the chat archive (scan for new sessions)
• User says "search my chats", "look up past sessions", "find in chat history"

Prerequisites

The copilot-session-tools CLI must be installed and available on PATH. It uses the Copilot CLI's built-in session store at ~/.copilot/session-store.db (requires Copilot CLI v0.0.412+).

Step 0: Ensure CLI is installed

Check if the CLI is available:

copilot-session-tools --help

If the command is not found, install it using whichever package manager is available (in preference order):

# Option 1: uv (recommended — fast, isolated)
uv tool install copilot-session-tools[all]

# Option 2: pipx (isolated)
pipx install copilot-session-tools[all]

# Option 3: pip (global)
pip install copilot-session-tools[all]

The [all] extra includes both the CLI and web viewer dependencies.

Favor CLI over Python

Always prefer CLI execution (copilot-session-tools commands) over writing Python scripts or importing the library directly. The CLI handles all common workflows. Only drop into Python/SQL when:

• You need a custom join or aggregation the CLI doesn't support
• You need to process results programmatically (e.g., pipe into another tool)
• The CLI's output format doesn't fit the task

For direct SQL queries, use sqlite3 on the database file rather than writing Python:

sqlite3 "$HOME/.copilot/session-store.db" "SELECT cs.session_id, cs.workspace_name, cs.created_at FROM cst_sessions cs ORDER BY cs.created_at DESC LIMIT 10"

Instructions

Search strategy (critical)

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:

✅ DO — these succeeded:

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

Step 1: Ensure the archive is fresh

Before searching, scan for new sessions (incremental — only imports changed files):

copilot-session-tools scan --verbose

This scans:

• VS Code Stable: %APPDATA%\Code\User\workspaceStorage\
• VS Code Insiders: %APPDATA%\Code - Insiders\User\workspaceStorage\
• Copilot CLI: ~\.copilot\session-state\ and ~\.copilot\history-session-state\

For a full reimport (slow, use only if data seems stale):

copilot-session-tools scan --full --verbose

Step 2: Search for content

Basic search

copilot-session-tools search "your search terms" --full --limit 30

Key flags:

Inline field filters

Field filters go directly in the query string (extracted before FTS processing):

# Filter by workspace
copilot-session-tools search "workspace:my-project error handling" --full

# Filter by repository
copilot-session-tools search "repo:github.com/owner/repo authentication" --full

# Filter by session title
copilot-session-tools search "title:build-loop pipeline" --full

# Filter by date range
copilot-session-tools search "start_date:2025-01-01 end_date:2025-06-30 docker" --full

# Filter by source edition
copilot-session-tools search "edition:cli ralph loop" --full

# Filter by role (inline)
copilot-session-tools search "role:user pipeline trigger" --full

# Combine multiple filters
copilot-session-tools search "role:user workspace:zts start_date:2025-06-01 docker build" --full

Exact phrase matching

Wrap phrases in double quotes (escape for shell):

copilot-session-tools search '"exact phrase match"' --full

FTS5 search tips

• word1 word2 → AND (both must appear)
• "exact phrase" → phrase match
• Field filters (role:, workspace:, repo:, title:, edition:, start_date:, end_date:) are extracted before FTS processing
• Sort by relevance (FTS5 rank, default) or date (session created_at DESC)
• Tool invocations and file changes use LIKE matching, not FTS

⚠️ Hyphenated terms crash FTS5. A bare query like copilot-session-tools is parsed as copilot MINUS chat MINUS archive, producing no such column: chat. Always wrap hyphenated terms in double quotes:

copilot-session-tools search '"copilot-session-tools"' --full

Step 3: Browse a specific session

When you have a session ID (from search results, a pasted path, or a URL):

Export as markdown (default — use this)

copilot-session-tools export-markdown --session-id <session-guid> --output-dir . --verbose

Optional detail flags:

• --include-diffs — Include file change diffs
• --include-tool-inputs — Include tool invocation inputs
• --include-thinking — Include reasoning/thinking blocks

Export as self-contained HTML (opt-in — for user presentation only)

copilot-session-tools export-html --session-id <session-guid> --output-dir . --verbose

Only use when the user explicitly wants a visual artifact to browse, share, or attach somewhere. The HTML is self-contained (embedded CSS/JS, dark mode, collapsible tool details) but adds no information beyond what markdown already provides. For LLM reading, always use markdown.

Alternatively, if the web viewer is running, download markdown via its API:

http://127.0.0.1:5000/api/markdown/<session-guid>?download=true&include_diffs=true&include_tool_inputs=true&include_thinking=true

Get session statistics

copilot-session-tools stats

Launch web viewer (for visual browsing)

copilot-session-tools web

Additional flags: --host (default 127.0.0.1), --port (default 5000), --title, --debug, --db (default ~/.copilot/session-store.db).

Then browse: http://127.0.0.1:5000/session/<session-guid>

The web viewer supports:

• Full-text search with highlight
• Workspace and edition filtering
• Download Markdown and Copy URL buttons per session
• Dark mode
• Syntax highlighting for code blocks
• Sticky header, multi-select filters, first-prompt display

Step 4: Extract session references from user input

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

Then use the session ID with export-markdown --session-id or raw-json to retrieve context.

Step 5: Get archive statistics

copilot-session-tools stats

Shows: session count, message count, workspace breakdown, edition breakdown, top repositories.

Step 6: Direct SQL for advanced queries

When the CLI search doesn't support your query shape, use SQLite directly:

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

# Find command runs
sqlite3 "$HOME/.copilot/session-store.db" `
  "SELECT s.session_id, cr.command, cr.status FROM cst_sessions s JOIN cst_messages m ON s.session_id = m.session_id JOIN cst_command_runs cr ON m.id = cr.message_id WHERE cr.command LIKE '%az pipelines%' ORDER BY cr.timestamp 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):

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

Common search patterns

These are real patterns observed from actual usage:

Workflow: "Continue where we left off"

When a user pastes a session path or URL and wants to resume work:

1. Extract the session GUID (see Step 4)
2. Export as markdown: copilot-session-tools export-markdown --session-id <guid> -o . Or as HTML: copilot-session-tools export-html --session-id <guid> -o .
3. Read the exported file to understand context
4. Summarize what was done and what remains
5. Continue the work in the current session

Workflow: "Find how we solved X before"

When a user wants to find a prior solution:

1. Search: copilot-session-tools search "<topic keywords>" --full --limit 30
2. Identify the most relevant session from results
3. Export that session: copilot-session-tools export-markdown --session-id <guid> -o .
4. Extract the relevant technique/solution
5. Apply it to the current situation

Known issues

• Hyphenated terms crash FTS5: Queries like copilot-session-tools fail because - is an FTS5 NOT operator. Always quote hyphenated terms: '"copilot-session-tools"'.
• Rich console crashes on pipe: The CLI uses Rich for console output, which can crash on Unicode box-drawing characters when piped. Workaround: don't pipe output; read it directly.
• 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.
• Requires Copilot CLI v0.0.412+: The session store database (~/.copilot/session-store.db) is created by the Copilot CLI's Chronicle feature, introduced in v0.0.412.

Related skills

• ado-build-ralph-loop: Uses this tool to find past build iteration patterns
• diagnose-ado-build-failures: Pairs with chat archive to find prior diagnosis approaches
• search-microsoft-repos-for-patterns: Broader search across engineering systems (not just local chats)