Shannon

Passively track every local AI coding-agent session — observability + a knowledge wiki, all on your machine.

Shannon is a VS Code extension that reads the session transcripts your AI agents already write to disk (no hooks, no wrappers, nothing leaves your machine) and turns them into:

• A unified Sessions view — every session from every agent, grouped by project, newest first; open one to read the full conversation.
• The Observatory — one tabbed webview with a shared date-range + per-agent filter driving every view: Dashboard (cost/tokens over time, by project, by model, token-mix, by agent), Insights (startup-tax, cache reuse, forecast), Patterns (activity by hour/day, model share, expensive sessions), Timeline (per-project chronology), and Best practices (actionable tips).
• Honest cost & token tracking — per-session/project token buckets (input / output / cache-read / cache-write) and cost (never fabricated), plus a status-bar heartbeat.
• A Karpathy-style wiki + knowledge graph — a Wiki view organized Projects → Sessions → Concepts. Each session becomes a synthesized page (Summary / Key Claims / Key Quotes / Connections / Contradictions); recurring concepts get their own pages (What it is / How it shows up / Related). Full-text search, backlinks, an interactive graph, and AI-consumable exports (graph.jsonld, llms.txt, per-page .txt/.json siblings, hashed manifest.json). The wiki requires synthesis (shannon.wiki.synthesis.enabled, your agent CLI) — with it off, no wiki is built (no filler). Useless sessions are routed to a reviewable junk area (see Shannon: Review Junk) and never clutter the wiki.
• An MCP server — a local, read-only stdio server (Shannon: Copy MCP Server Config) so your agents can wiki_search / wiki_read_page / wiki_query the knowledge base directly.

Supported sources

Privacy

Local by default. Ingestion, browsing, cost, wiki reading, and the graph all work with no network access. Secrets (API keys, tokens, emails) are redacted before any content enters a wiki page. The only feature that can send content off-machine is opt-in wiki synthesis, which shells out to a configurable agent CLI (default GitHub Copilot CLI) using your own subscription — and it degrades to a no-LLM structural wiki when disabled or unavailable.

Install / run (from source)

npm install
npm run build      # esbuild bundles the extension + graph webview
# press F5 in VS Code (Run Extension), or:
npm run package    # produces shannon-<version>.vsix  ->  code --install-extension shannon-<version>.vsix

Requires VS Code ≥ 1.104 (uses the built-in node:sqlite; no native binaries).

Commands

Shannon: Open Observatory (Now · Months · Dashboard · Insights · Patterns · Timeline · Best practices), Rescan Sessions, Open Session, Open Dashboard/Open Insights (open the Observatory on that tab), Build/Update Wiki, Open Wiki, Search Wiki, Open Knowledge Graph, Export Wiki, Summarize Project (wiki), Drain Project (full index), Filter Wiki by Tag, Review Junk, Copy MCP Server Config.

The Now view shows a budget gauge + projected month-end + alerts; Months compares monthly spend vs budget; Best practices maps the four P&G credit rules (model tier, cache reuse, repo map, heavy sessions) to your usage. Filter every view by agent, model, project, and date range. Drain Project synthesizes a whole project's sessions in bounded batches (resumes after a window reload); Summarize Project writes a durable project overview wiki page.

Using the MCP server

MCP (Model Context Protocol) is a standard way for AI agents (Claude Code, Cursor, Copilot CLI…) to connect to external tool servers. Shannon ships one so your agents can query the wiki you've accumulated — read-only and local, no network.

1. Run Shannon: Copy MCP Server Config. It copies a JSON snippet like:

   {
     "mcpServers": {
       "shannon-wiki": {
         "command": "node",
         "args": ["<extension>/out/mcp-server.js"],
         "env": { "SHANNON_DATA_DIR": "~/.shannon" }
       }
     }
   }
   

2. Paste it into your agent's MCP config file:
   • Claude Code: ~/.claude.json (or claude mcp add)
   • Cursor: ~/.cursor/mcp.json
   • Copilot CLI: ~/.copilot/mcp-config.json
3. Restart the agent. It now has three tools: wiki_search, wiki_read_page, and wiki_query (graph traversal).

The MCP server is optional — the Observatory, wiki, and graph all work without it. It only lets other agents read Shannon's knowledge base.

Configuration (shannon.*)

sources.enabled, dataDir (default ~/.shannon), ingest.debounceMs, wiki.synthesis.enabled / .command (default copilot -p {prompt}) / .timeoutMs, redaction.patterns, cost.unit (usd|credits), cost.pricesPath. Set your real model rates in assets/prices.json; add an optional per-model "tier" (powerful|versatile|lightweight) to drive Best-practices Rule 1. Budget lives in assets/budget.json: monthlyCredits (drives the Now gauge / Months % / alerts), alertThresholds (default [0.5, 0.8, 1.0]), githubCycleCredits (the authoritative org-cycle figure for reconciliation), and usdToCredits.

Development

Spec-driven with spec-kit; see specs/001-session-observability-wiki/ and .specify/memory/constitution.md. Tests: npm test (Node's built-in node:test — no test dependencies).

License

MIT