context-os is an open-source tool for coding agents (Claude Code, Codex, Cursor, OpenCode, etc.), designed to reduce context bloat and cost leakage for agents in code repositories. Its core idea is that before the agent's first round of conversation, it builds a repository graph through local static analysis (including symbols, import relationships, and git hotspot files), and injects ranked file:line candidates, so that the agent directly opens the correct file instead of executing the Glob → Grep → Read exploration process. This process requires no embeddings, no server, and no model calls, and completes in about 50 milliseconds.
Main capabilities include:
- auto_context: injects retrieval results during the UserPromptSubmit stage, skipping the first round of exploration.
- smart_read: intercepts whole-file reads during the PreToolUse stage and returns a file outline (each symbol and its exact line range), so the agent reads only the needed fragments, avoiding large files repeatedly entering the context.
- savings_tracker: causally measures savings during the Stop stage based on real tool result sizes, and displays them through the /savings command.
- Cost leakage CI gate: provides a GitHub Action for detecting cost leakage signals in agent workflows.
- Retrieval quality CI gate: cross-repository evaluation (MRR 0.545 vs. best lexical baseline 0.461, an 18.2% improvement), and sets a quality floor in CI.
Usage:
- Run setup.sh to install 31 techniques, writing CLAUDE.md, .claudeignore, .claude/settings.json, thirteen slash commands, output styles, a Haiku exploration subagent, and nine standard-library Python hooks (located in .claude/hooks/).
- Behavior can be controlled through environment variables, such as CONTEXT_OS_SMART_READ=0 to disable smart_read.
- Provides a local replay script: python3 python/evals/runners/replay_history.py . can backtest results based on historical records, without an API key.
- Provides a 60-second demo: bash docs/distribution/demo.sh.
- Provides a versioned GitHub Action and CI recipe documentation.
Applicable scenarios:
- Teams using coding agents such as Claude Code, Codex, and Cursor that want to reduce first-round tool calls, latency hitting context limits, and compaction.
- More noticeable in navigation-intensive interactive work (such as frequently finding files and understanding code structure); less effective in long autonomous build runs.
- Teams that need cost leakage audits for private repositories can purchase a paid audit service (48 hours, 2 slots), but the open-source tool itself is free and MIT licensed.
Limitations and notes:
- Does not perform LLM routing, model switching, or prompt rewriting; no proxy, Claude Code communicates directly with Anthropic; no telemetry, no callbacks, no analytics.
- Symbol extraction is regex-based, supports Python, TS/JS, Rust, and Go, and other languages fall back to path-only ranking.
- Hooks add about 12–15% input overhead per round, amortized within 1–2 rounds in non-trivial repositories; p99 latency is 118 milliseconds at 10,000 files and 589 milliseconds at 50,000 files.
- In repositories where the prompt already explicitly specifies class names (such as psf/requests calling PreparedRequest), tuned BM25 can match it.
- Live A/B was 36 calls and 6 prompts, p < 1e-6 but not Anthropic scale; a one-off call with a cold cache showed −40.9% tokens, but in hot interactive sessions prompt caching reduces the cost of resending context, so actual dollar savings are small.
- Compatible with Claude Code on macOS + Linux, requires python3 (standard library only); an optional Rust binary (apps/cli) adds output compression and session memory hooks.
- All hooks fail open; if an error occurs, the session continues.
- Uninstallation removes only the <!-- context-os --> block in CLAUDE.md and files written by context-os, and is idempotent.
The project is MIT licensed; see LICENSE for details.
