Global session history registry and copilot --history flag — persistent cross-session stats and audit log accessible without starting the agent

[berrat]

Describe the feature or problem you'd like to solve

Every Copilot CLI session is isolated — when it ends, its context and metadata are effectively gone from any accessible view. There is no persistent, cross-session record of what was run, where, when, for how long, with which model, or at what cost. Users who want to understand their usage patterns, audit past sessions, track productivity, or simply recall what they worked on last Tuesday have no facility to do so. The only existing data is buried in per-session events.jsonl files with no aggregated view or queryable interface.

Additionally, this information should be accessible without launching the full agent — querying session history should not consume a premium request or spin up the LLM.

Proposed solution

Introduce a persistent global session registry — a lightweight, append-only index written to ~/.copilot/session-history.db — that records a structured summary for every session at open and close time. This data is then exposed via:

1. A /history slash command — inside an active session, for interactive browsing
2. A copilot --history CLI flag — invokable directly from the shell, without starting the agent or consuming any quota

Data captured per session:

Field	Description
Session ID	Unique session identifier
Started at	Timestamp of session start
Ended at	Timestamp of clean exit (or crashed / killed)
Duration	Wall-clock duration
Working directory	Absolute path at session start
Git branch	Branch name at start (if in a repo)
Model	Primary model used
Reasoning effort	low / medium / high
Total turns	Number of prompts submitted
Tokens sent	Cumulative input tokens
Tokens received	Cumulative output tokens
Cached tokens	Tokens served from prompt cache
API calls	Total LLM requests
Premium requests	Count of premium-model calls
MCP servers	Names of active MCP servers
Sub-agents launched	Count and types
Compactions	Number of context compaction events
Exit status	clean / crashed / killed / timed-out

copilot --history output (shell, no agent, no quota):

$ copilot --history

  GitHub Copilot CLI — Session History  (last 10 sessions)

  #   Started              Duration   Dir                    Model               Turns  Tokens↑   Premium  Exit
  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────
  1   2026-03-03 01:05     48m 12s    ~/repos/myapp          claude-sonnet-4.5   14     118,420   6        clean
  2   2026-03-02 22:14     12m 03s    ~/repos/myapp          claude-sonnet-4.5    5      31,200   2        clean
  3   2026-03-02 18:40      3m 55s    ~/repos/timer          claude-sonnet-4.5    2       8,100   1        crashed ⚠
  4   2026-03-01 15:22     1h 02m     ~/repos/myapp          claude-opus-4.5     21     290,000   21       clean
  ...

  Totals (all time):  48 sessions · 18h 32m · 1.2M tokens sent · 89 premium requests

Flags:

copilot --history             # Show last 10 sessions (default)
copilot --history --all       # Show all sessions
copilot --history --limit 25  # Show last N sessions
copilot --history --json      # Machine-readable JSON output
copilot --history --stats     # Aggregate totals only (no per-session rows)
copilot --history --dir .     # Filter to sessions started in current directory
copilot --history --since 7d  # Sessions from last 7 days

/history inside the agent opens the same data in an interactive alt-screen table with sorting, filtering, and the ability to select a past session row and ask the agent questions about it.

Example prompts or workflows

1. copilot --history --stats — user checks monthly premium request consumption before their billing cycle resets, zero tokens spent.
2. copilot --history --dir . --since 30d — user reviews all sessions in the current repo over the last month to recap progress for a sprint review.
3. /history inside the agent, user selects a past session row and asks "summarise what I did" — agent uses the session metadata as context.
4. copilot --history --json | jq — power user pipes session data into a custom dashboard or spreadsheet.
5. DevOps team runs copilot --history --json in a post-session hook to log usage telemetry to an internal system.
6. User sees crashed ⚠ in the exit status for yesterday's session — immediately knows to run /cleanup (/cleanup slash command — detect and resolve orphaned, stale, and hung processes from previous sessions #1790) to check for leftover state.

Additional context

• OS: Windows 11 Pro (Build 26200 / 24H2)
• Shell: PowerShell 7.5.4
• Copilot CLI: 0.0.420 (win32-x64)
• copilot --history must never invoke the LLM — it is a pure local read of the session registry. No API calls, no tokens, no premium requests.
• Per-session events.jsonl files already exist in ~/.copilot/session-state/ — the registry aggregates from these at session close, requiring no new data collection infrastructure.
• The /chronicle command (added in 0.0.419, experimental) generates standups from session history — a queryable registry would give /chronicle a richer and more reliable data source.
• Related: /cleanup slash command — detect and resolve orphaned, stale, and hung processes from previous sessions #1790 (/cleanup) — exit status in the registry (crashed, killed) feeds directly into cleanup workflows.
• Related: Collapsible real-time session stats panel (tokens, context, API calls, premium requests, cache, duration) #1784 (Session Stats panel) — the panel shows live per-session stats; the registry is the persistent historical record across all sessions.