CtxGuard CLI
Local proxy between agent and model API: compresses diffs and logs, keeps the request prefix stable for prompt caching.
- 189 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The proxy sees every request and the provider keys passing through it.
- Output compression can hide a line from the model that turns out to matter.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/ctxguardDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The proxy sees every request and the provider keys passing through it.
- Output compression can hide a line from the model that turns out to matter.
This is third-party code. Review the repository files before installing.
What it does
CtxGuard is a FastAPI reverse proxy that sits between an agent (Claude Code, Codex, Pi Agent) and a provider API such as OpenAI, Anthropic, Gemini, xAI or DeepSeek, trimming context on the way. Code is folded to signatures and docstrings with Tree-sitter, folded bodies stay in a local SQLite pool and return on the model's request. Repeated `ls` and `git status` output becomes a diff against the previous snapshot, long build and test logs keep the first 25 and last 75 lines, and keys and tokens in text are masked. Its second job is keeping the provider's prompt cache warm: tool schemas are sorted deterministically, unchanged messages are forwarded byte for byte, and thinking blocks pass through untouched. A dashboard at `http://127.0.0.1:8787/dashboard` shows the effect. The author claims a 50 to 80 percent token reduction; the README gives no independent verification.
Who it is for. Developers running Claude Code or Codex through long sessions who pay for context and want a savings meter and a proxy that needs no change inside the agent.
Good fit when
- A long agent session hits the context window because of build logs and repeated directory listings.
- The provider's prompt cache keeps resetting because the client serializes tool schemas inconsistently.
- A local dashboard with token trends and a per-turn request log is wanted.
- The agent is launched with one command that swaps the API base URL automatically.
Not a fit when
- All model traffic must not pass through another process, even a local one.
- The task is open-ended and any output compression could hide an important line.
- The agent's built-in context compaction is enough.
Example request
Start CtxGuard locally, run Claude Code through it and show on the dashboard how many tokens went to build logs.Limitations
The proxy sees every request and reads the provider address and key from client configuration such as `~/.claude/settings.json`, so run it only on your own machine and keep the port closed. Code and log folding changes what the model sees, and the savings figures come from the author's README. Documentation is in Chinese only; the last commit is from October 2026. The project is young: 189 stars, a single author, and compression behavior may change between releases.
How to disable. Stop the `ctxguard` process and start the agent directly, without `ctxguard wrap`. If you set variables with `eval $(ctxguard env --eval)`, close that terminal.
FAQ
How do I run an agent through the proxy without editing configs?
Run `ctxguard wrap claude`: it starts the gateway on port 8787 and injects the API base URL only into the agent process. `wrap codex` and `wrap pi` cover Codex and Pi Agent.
How do I enable the proxy in the current terminal?
Run `eval $(ctxguard env --eval)`: the environment variables apply to that session, then start `claude` or another agent as usual.
What happens to model thinking blocks?
They pass through unchanged. The author never edits thinking blocks, to avoid signature errors at Anthropic and cache misses at Gemini and DeepSeek.
Can folded code be restored?
Yes. The function body is stored in a local SQLite pool with a reference marker, and the model can request the full text by that marker.
Which providers are supported?
Per the README the gateway fronts OpenAI, Anthropic, Google Gemini, xAI Grok and DeepSeek. The provider address is taken from client configuration when you use `ctxguard wrap`.
Discussion
No questions or reviews yet.
Related
CLI toolsA local proxy and plugin for Claude Code and Codex that trims tool output, keeps the prompt cache warm and shows the savings
A Rust program that shrinks the command output an agent reads: drops build and test noise, folds repeated file reads and redacts credentials
Paritok is a proxy between a coding agent and the model API that compresses requests and cuts the input-token bill.
Local context compression for agents: tool outputs, logs, files and RAG chunks shrink before reaching the LLM. Proxy, CLI, library and MCP
A local OpenAI-compatible proxy that caches repeated agent requests and replays stored answers without calling the model.
A local proxy with a terminal dashboard: shows how many tokens each Claude Code and Codex request sends and saves the prompts to files
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| CtxGuard (this card) | no | 189 | ||
| SuperCompress | no | API key | 146 | compresses output through an MCP tool on demand; CtxGuard is a proxy in front of the API and handles all traffic without tool calls |
| LeanToken | no | not required | 158 | searches code locally under a context budget; CtxGuard compresses requests already in flight and protects the prompt cache |
README in short
One proxy that combines context compression, prompt-cache prefix protection and secret masking, with a dashboard.