SkillFoxx

ContextSpy CLI

A context profiler: a proxy captures an agent's requests to the model and shows what each request is made of and where tokens go.

  • 67 ★ on the repository
  • Last commit
  • Apache-2.0
CLI

Broad access

Why this level

  • The proxy captures all agent traffic to the provider, including request and file contents, and stores it in an on-disk database.
  • The `install-cert` command changes the operating system trust store.
All reasons and checks

rimantasz/contextspyAuthor:RimantasZ

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add cli/contextspy

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • The proxy captures all agent traffic to the provider, including request and file contents, and stores it in an on-disk database.
  • The `install-cert` command changes the operating system trust store.

This is third-party code. Review the repository files before installing.

What it does

ContextSpy starts a local HTTPS proxy (a reverse proxy for local models) that captures a coding agent's requests to a model API, analyses their composition and stores the result in a local SQLite database. A dashboard at `http://127.0.0.1:5173` shows session and provider summaries, model and latency breakdowns, a tool-use treemap and a request workbench with compact, relative-size and raw views. In a session view ContextSpy reconstructs the conversation: continuations, forks and the blocks that persisted, were added, vanished or were replaced. The agent is launched through the proxy with a command such as `contextspy run claude`. Verified combinations are collected on the confirmed-configurations page; for Claude Code that is the Anthropic API on macOS and Windows. The README also names Codex CLI, opencode and GitHub Copilot.

Who it is for. Developers who track token use and latency in Claude Code, opencode or Codex CLI sessions and look for what bloats the context.

Good fit when

  • The API bill is growing and you need to see how many tokens go to the system prompt, skills and tool results.
  • A session slows down by turn twenty-five and you need to see which blocks accumulate in the context.
  • You added a new skill or MCP server and want to measure how much it adds to every request.
  • You want to compare how two sessions continue each other and where they fork.

Not a fit when

  • You need permanent monitoring: the author recommends running ContextSpy on dedicated profiling sessions.
  • Requests are confidential: the proxy stores request and response contents in a local database.
  • The agent or provider is missing from the confirmed configurations and you need a guarantee it works.

Example request

Start ContextSpy and a Claude Code session through it, then show which blocks make up the largest request.

Limitations

The proxy sees all agent traffic to the provider and stores it locally, request contents included. Cloud mode needs a certificate: `sudo contextspy install-cert` adds it to the system store. Claude Code on Node ignores the system store, so `NODE_EXTRA_CA_CERTS` is required. Data is never deleted on its own: you archive a session and clear the database with `contextspy reset-db`. Of the Codex products only Codex CLI works, not the desktop app.

How to disable. Stop the proxy, run `contextspy reset-db`, remove the certificate from the system store and uninstall the package with `brew uninstall contextspy`. Launch the agent without `contextspy run`.

FAQ

How do I install ContextSpy?

On macOS: `brew tap RimantasZ/contextspy`, then `brew install contextspy`. The install guide also covers Linux, Windows and PyPI.

How do I launch an agent through the proxy?

Run `contextspy start`, then in another terminal `contextspy run claude`, `contextspy run codex` or `contextspy run opencode <project path>`.

Does ContextSpy send data to the cloud?

No. Everything stays on your computer, and the proxy and dashboard listen on localhost only.

How do I clear stored requests?

Archive a session with the Archive button or `contextspy session archive`; the whole database is cleared with `contextspy reset-db`.

Why is install-cert needed?

Cloud mode needs a trusted certificate so the proxy can read HTTPS requests. The command installs it into the system store once.

Discussion

No questions or reviews yet.

CLI tools

A CLI records coding agent sessions locally, replays what happened and shows what the trace could not prove.

CLIExtended access104

Local documentation for agents: an MCP server searches a library of doc packages for 100+ libraries and answers offline

MCP serverMinimal access439

An HTTP gateway for Claude Code and Codex switches API endpoints on failure and converts requests between model formats

CLIBroad access971

An MCP server in one binary: AI reads and edits files across several projects and runs your commands

MCP serverBroad access342

Ctxo builds a repository dependency graph and gives an agent the blast radius of a change, commit history and code health over MCP

MCP serverExtended access74

README in short

The project turns context use into a visual profile: how many tokens go to which request blocks and how they change between calls. The package ships through Homebrew and PyPI under the Apache 2.0 licence, and the database schema still changes between versions.

README badge

Report a problem