ContextScope

Local-first context debugger for AI agents: capture redacted snapshots at LLM boundaries (segments, token estimates, diffs, signal scores), store them in SQLite, and inspect them in a DevTools-style dashboard plus CLI.

Scope: Callback-based capture (LangChain chat-model start, OpenAI Agents RunHooks, OpenAI-compatible proxy, shell harness). Context is redacted before persistence; token totals are offline estimates, not provider billing.

Install (first time)

Use python3 on macOS if python is missing. Install inside a venv to avoid PEP 668 errors.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cd dashboard && bun install && bun build ./index.html --outdir ./dist && cd ..

• Core only (no tests): pip install -e .
• Framework examples in examples/ need extras, e.g. pip install -e ".[langgraph]" — not required for the smoke test below.

Run

ctxscope serve

• Dashboard + API: http://127.0.0.1:8765 (default).
• Health: GET /health → {"ok": true}.

Build the dashboard once (see install) so the UI is bundled; without dashboard/dist, / returns 503 with build instructions.

Quick test (no API keys)

Terminal 1 — server:

source .venv/bin/activate
ctxscope serve

Terminal 2 — capture via harness:

source .venv/bin/activate
ctxscope run -- python -V

Open the dashboard → you should see a new session and snapshot.

Common commands

Command	Purpose
ctxscope serve	API + dashboard
ctxscope proxy	OpenAI-compatible proxy (default :8766); set client base URL to http://127.0.0.1:8766/v1 (legacy: .../proxy/openai/v1)
ctxscope analyze <session_id>	Text summary
ctxscope export <session_id> [-o file]	Redacted JSON
ctxscope gc --days N / --max-mb N	Prune SQLite (at least one flag required)
ctxscope run -- <cmd...>	Run a command with harness capture

Environment (short reference)

Variable	Purpose
CTXSCOPE_DB	SQLite path (default ./ctxscope_data/ctxscope.db)
CTXSCOPE_SERVER_URL	Where captures are POSTed (default matches serve URL)
CTXSCOPE_DISABLE_EMBEDDING	1 → heuristic scores only (skips embedding model load)
CTXSCOPE_PROXY_UPSTREAM	Upstream for ctxscope proxy (default https://api.openai.com)
CTXSCOPE_HOOK_SECRET	If set, integration hooks need header X-ContextScope-Token
CTXSCOPE_HOST_MODEL	Model label for Claude Code / OpenCode snapshots

Integrations & docs

• Cursor / VS Code sidebar: integrations/cursor/README.md
• Claude Code hooks: integrations/claude-code/README.md
• OpenCode plugin: integrations/opencode/README.md
• Privacy: docs/PRIVACY.md
• Optional cloud sync stub: cloud/README.md

Tests

source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -q

License

MIT