copilot-session-tools 0.10.4

A collection of tools for VS Code GitHub Copilot chat history

Copilot Session Tools

Search, browse, and enrich your GitHub Copilot chat history — across Copilot CLI, VS Code, and VS Code Insiders.

Works out of the box with the Copilot CLI's built-in session store (Chronicle). Sessions are browsable immediately; run scan to enrich them with full detail (tool calls, file changes, diffs, thinking blocks) and import VS Code desktop sessions.

Prerequisites

Copilot CLI v0.0.412+ is recommended. This version introduced cross-session memory ("Chronicle"), which creates ~/.copilot/session-store.db. When present, copilot-session-tools can discover CLI sessions from Chronicle for enrichment. Update with:

copilot --update

Quick Start

1. Install

pip install copilot-session-tools[all]

Also works with pipx install or uv tool install for isolated environments.

2. Browse your chats immediately

No scan needed — the web viewer reads directly from the Copilot CLI's session store:

copilot-session-tools web
# Open http://127.0.0.1:5000/

All your CLI sessions appear immediately with basic data (titles, user messages, assistant responses):

3. Enrich for full detail

Click Scan Now on any session, or run a bulk scan to enrich everything at once:

# Enrich all CLI sessions + import VS Code desktop sessions
copilot-session-tools scan

# Or enrich a single session by ID
copilot-session-tools enrich <session-id>

Enriched sessions gain tool invocations, file diffs, command output, thinking blocks, and more:

4. Search across all sessions

copilot-session-tools search "authentication" --full

5. Use the AI agent skill

If you use an AI coding agent (Copilot CLI, Claude Code, Cursor, etc.), install the search-copilot-chats skill for natural-language chat search:

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

Then ask your agent: "search my chats for how I fixed the auth bug"

Under the hood, the skill calls copilot-session-tools search and export-markdown.

How It Works

This tool stores enriched session data in its own database (~/.copilot/copilot-session-tools.db), separate from the Copilot CLI's Chronicle database (session-store.db). Chronicle is optionally read for CLI session discovery and unenriched fallback — but is never modified.

Two-tier rendering:

Tier	Data Source	What You See	When
Unenriched	Chronicle sessions + turns tables	Session title, user messages, assistant text	Immediately, no scan needed (requires Chronicle)
Enriched	cst_* tables in copilot-session-tools.db	Tool invocations, file diffs, command output, thinking blocks, content blocks	After running scan or enrich

If new turns arrive after enrichment (e.g., you continued a conversation), the web viewer appends them below the enriched messages with a "new since last scan" divider.

VS Code sessions (Stable and Insiders) are imported during scan from workspace storage. They're always enriched on import since there's no built-in tier for VS Code.

Searching

# Basic search (FTS5 full-text search)
copilot-session-tools search "React hooks" --full

# Filter by role, workspace, edition, date
copilot-session-tools search "role:user workspace:my-project error" --full
copilot-session-tools search "edition:cli start_date:2026-01-01 deploy" --full

# Search only tool invocations or file changes
copilot-session-tools search "git" --tools-only
copilot-session-tools search "Dockerfile" --files-only

# Sort by date instead of relevance
copilot-session-tools search "python" --sort date --limit 50

Search tips: FTS5 uses AND logic — every keyword must appear in the same message. Start with 1–2 keywords, then narrow. Wrap hyphenated terms in quotes: '"copilot-session-tools"'.

Scanning & Enrichment

# Scan everything (VS Code Stable + Insiders + enrich CLI sessions)
copilot-session-tools scan

# Scan only one VS Code edition
copilot-session-tools scan --edition stable
copilot-session-tools scan --edition insider

# Force full re-import
copilot-session-tools scan --full

# Enrich a single CLI session
copilot-session-tools enrich <session-id>

The web viewer's Scan Now button on unenriched sessions triggers single-session enrichment without a full scan.

Scanning is incremental by default — only new and changed sessions are processed.

Exporting

# Export as Markdown
copilot-session-tools export-markdown --output-dir ./archive --include-diffs

# Export a single session
copilot-session-tools export-markdown --session-id <id> --output-dir .

# Export as self-contained HTML (dark mode, collapsible sections, no server needed)
copilot-session-tools export-html --output-dir ./html-archive

# Export all sessions as JSON
copilot-session-tools export --output chats.json

# Import from JSON
copilot-session-tools import-json chats.json

Web Viewer

copilot-session-tools web                    # defaults to port 5000
copilot-session-tools web --port 8080        # custom port
copilot-session-tools web --db custom.db     # custom database

Features:

• Full-text search with keyword highlighting
• Edition badges (CLI, VS Code Stable, VS Code Insiders) with counts
• Repository and workspace filtering
• Enrichment status — see which sessions have full detail vs. basic turns
• Copy Markdown toolbar — select message range, include/exclude diffs, tool inputs, thinking
• Download markdown or copy session URL
• Transcript cleanup — clean up voice-dictated messages using LLM (see below)
• Dark mode via CSS prefers-color-scheme
• Incremental refresh without restarting

Transcript Cleanup

Voice-dictated user messages often come out garbled (repeated words, filler words, broken sentences). Transcript cleanup uses an LLM to rewrite them, using the assistant's response and reasoning as context for what you actually meant.

# Clean up a single session (auto-detects voice-dictated messages)
copilot-session-tools cleanup <session-id>

# Preview changes without writing
copilot-session-tools cleanup <session-id> --dry-run

# Clean all user messages (skip auto-detection)
copilot-session-tools cleanup <session-id> --all

# Clean a specific message
copilot-session-tools cleanup <session-id> --message 5

# Revert all cleaned messages to originals
copilot-session-tools cleanup-revert <session-id>

# Revert a single message
copilot-session-tools cleanup-revert <session-id> --message 5

# List sessions with potential voice-dictated messages
copilot-session-tools cleanup

Requires the [llm] extra (uses LiteLLM with the GitHub Copilot provider):

pip install copilot-session-tools[llm]

How it works:

1. A pure-Python heuristic pre-filter scores each user message (repeated words, filler density, missing punctuation)
2. Messages above the threshold are batched into a single LLM call with context (assistant response + thinking traces + tool inputs)
3. The LLM classifies each as typed or voice-dictated and cleans the voice-dictated ones
4. Originals are preserved — you can always revert

Web viewer integration: Each user message shows a 🎙️ mic icon — gray (not cleaned), green (cleaned), or amber (showing original). Click to open a popover with toggle/revert/clean actions. Session-level cleanup and revert-all buttons are in the toolbar.

Session Sources

Source	Format	Location
Copilot CLI	JSONL events	~/.copilot/session-state/
VS Code Stable	JSON / JSONL	%APPDATA%/Code/User/workspaceStorage/*/
VS Code Insiders	JSON / JSONL	%APPDATA%/Code - Insiders/User/workspaceStorage/*/

On macOS/Linux, replace %APPDATA% with ~/Library/Application Support or ~/.config respectively.

Agent Skills

This repository includes Agent Skills for AI coding agents:

Skill	Description
search-copilot-chats	Search, browse, and export Copilot chat sessions. Triggers on "search my chats", "find in chat history", session GUIDs, or web viewer URLs. Calls copilot-session-tools search and export-markdown under the hood.
scanner-refresh	Research recent changes in Copilot CLI/VS Code repos and update the scanner for new event types.

# Install for your agent (Claude Code, Cursor, VS Code, Codex, etc.)
npx skills-installer install @Arithmomaniac/copilot-session-tools/search-copilot-chats
npx skills-installer install @Arithmomaniac/copilot-session-tools/search-copilot-chats --client cursor

Skills are also available automatically when working in this repository.

Database Schema

The tool writes to cst_* enrichment tables alongside the CLI's built-in tables:

Table	Contents
cst_sessions	Enriched session metadata (workspace, edition, parser version, source format)
cst_messages	Parsed messages with content blocks, transcript cleanup (original_content, cleanup_model)
cst_messages_fts	FTS5 full-text search index
cst_tool_invocations	Tool calls (name, input, result, status)
cst_file_changes	File edits with diffs
cst_command_runs	Shell commands and output

Recovery: If cst_* tables get corrupted, just delete the database and re-scan. Chronicle data is completely unaffected since it lives in a separate file:

rm ~/.copilot/copilot-session-tools.db
copilot-session-tools scan --full

Installation Options

pip install copilot-session-tools[cli]     # CLI only
pip install copilot-session-tools[web]     # Web viewer only
pip install copilot-session-tools[all]     # CLI + web + LLM
pip install copilot-session-tools[llm]     # Optional: transcript cleanup via LiteLLM (GitHub Copilot API)
pip install copilot-session-tools[vector]  # Optional: hybrid FTS5 + vector search (sqlite-vec + sentence-transformers)

Development

git clone https://github.com/Arithmomaniac/copilot-session-tools.git
cd copilot-session-tools
uv sync --all-extras
uv run pytest tests/ --ignore=tests/test_webapp_e2e.py -v
uv run ruff check . && uv run ruff format . && uv run ty check

Acknowledgments

This project was informed by several excellent open-source projects:

Project	Inspiration
simonw/claude-code-transcripts	HTML transcript generation, web viewer design
Arbuzov/copilot-chat-history	VS Code session data format
tad-hq/universal-session-viewer	FTS5 search design

License

MIT License — see LICENSE for details.