Context Mode — Context Optimization for AI Coding Agents
Cut context window bloat, persist session memory, and enforce tool routing across 17 platforms via MCP and hooks.
- Source repo
- mksglu/context-mode
- Stars
- ★ 31k
- Last updated
- today
- License
- NOASSERTION
- Primary language
- TypeScript
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Claude Code user installs the plugin and uses
/context-mode:ctx-doctorto verify, with hooks automatically redirecting large tool calls to sandbox execution. - Not a fit if
- Teams without Node.js >= 22.5 installed on every platform
- Teams needing 100% routing enforcement on non-hook platforms like Cursor or Zed
- Users unwilling to add rules files or edit platform config files
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Context Mode is an MCP server that solves the problem of AI coding agents' context windows being flooded by tool output. It sandboxes tool execution to keep raw data out of context (e.g., 315 KB → 5.4 KB, a 98% reduction) and persists session events (file edits, git operations, tasks, errors, user decisions) into SQLite, using FTS5 and BM25 search to restore key state after conversation compaction. The project promotes a "think in code" paradigm where the model writes scripts that compute results and output only stdout, rather than reading many files into context. Context Mode supports 17+ platforms including Claude Code, Gemini CLI, Copilot, Cursor, OpenCode, and others, with hooks or routing files for enforcement, and it works as an MCP server. It provides 11 MCP tools like ctx_execute and slash commands like ctx-stats and ctx-doctor. The project is licensed under ELv2 and targets developers and teams using LLM-assisted coding.
Context Mode registers itself with supported clients via MCP or plugins. When the model calls tools, hooks or routing rules guide it to prefer sandboxed tools like ctx_execute and ctx_batch_execute, which run code in separate subprocesses and only return stdout to context. ctx_index chunks markdown by headings while preserving code blocks, storing in SQLite FTS5; ctx_search uses BM25 and Reciprocal Rank Fusion to retrieve indexed content. ctx_fetch_and_index fetches URLs, converts to markdown, chunks, and indexes with TTL caching. Session events are captured by hooks like PreToolUse and PostToolUse into SQLite; before compaction, PreCompact hooks save snapshots, and on session resume, SessionStart injects relevant state. ctx_stats reports context savings.
- A Claude Code user installs the plugin and uses
/context-mode:ctx-doctorto verify, with hooks automatically redirecting large tool calls to sandbox execution. - A Gemini CLI developer registers MCP and hooks via one config file, reducing context usage and maintaining session continuity.
- A Cursor user manually configures
.cursor/hooks.jsonand rules file to protect context in the IDE, as the Marketplace plugin is pending review. - A Codex CLI user enables plugin and hooks feature flags to ensure state restoration after conversation compaction.
- A team uses
ctx_indexandctx_searchto build a project knowledge base for on-demand retrieval without loading large documents. - An OpenCode user uses the TypeScript plugin to get native
ctx_*tools and hooks, with session snapshots during compaction.
How do you install or deploy this agent?
For Claude Code: run /plugin marketplace add mksglu/context-mode and /plugin install context-mode@context-mode, then restart and verify with /context-mode:ctx-doctor. For other platforms, install Node.js >= 22.5, npm install -g context-mode, then copy the platform-specific MCP config, hooks file, and routing rules. Full steps in README.
How do you use this agent?
After installation, type ctx stats in a supported client to see savings, ctx index to index a file, ctx search to query, and ctx doctor to diagnose. Sandbox tools like ctx_execute are automatically invoked by the model or can be used manually.
What are this agent's strengths and limitations?
- Sandboxed tools can reduce tool output by up to 98% (e.g., 315 KB → 5.4 KB), drastically preserving context.
- Session continuity is robust, with hooks and SQLite restoring file and task state after compaction.
- Supports 17+ platforms including Claude Code, Gemini CLI, Cursor, Codex, with automatic or manual routing.
- Non-hook platforms like Antigravity IDE and Zed rely on rule files, achieving only ~60% routing compliance, offering weaker protection.
- Requires Node.js >= 22.5 and all platforms need Node installed.
- Some platforms like Cursor lack SessionStart hooks, requiring extra rules file; Cursor plugin is awaiting review.
How does this agent compare with similar options?
Compared to other AI coding assistants without context optimization, Context Mode's unique selling point is its sandboxed execution and SQLite-based session persistence, not just prompt compression.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Context Mode — Context Optimization for AI Coding Agents This agent | 54 · Major gaps | MCP serverFree | ★ 31k | today | TypeScript | ChatGPT · Codex · Claude Code |
| Ori Mnemos | 80 · Good | CLIFree | ★ 332 | 18d ago | TypeScript | Claude Code · OpenAI API · Claude API |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 157 | today | Python | Codex · Claude Code · Claude.ai |
| Claudex | 69 · Some gaps | CLIFree | ★ 97 | 4mo ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: tool sandboxing (ctx_execute etc.) reduces raw data entering context, but permission model does not explicitly follow least privilege; user confirmation exists (e.g., ctx_purge requires confirmation) but not comprehensive; data flow transparency is good, README details data flow; sensitive data handling (e.g., session data) has deletion mechanism but no explicit encryption; dependency security not audited; external effects (e.g., web fetch) sandboxed but not explicitly restricted; rollback mechanism exists (ctx_upgrade can fix) but not explicit data rollback; source attribution clear (author, repo) but publisher unverified. Deductions: permission model not explicit least privilege, user confirmation not comprehensive, sensitive data not encrypted, dependencies not audited, external effects not explicitly restricted, rollback incomplete, publisher unverified.
Evidence shows: self-consistency good, README consistent with code; dependency availability not verified (static review); failure messages provided (e.g., ctx-doctor diagnostics) but not comprehensive. Deductions: dependency availability not verified, failure message coverage incomplete.
Evidence shows: audience clear (AI coding agent users), scenarios diverse (17 platforms); capability boundaries clear (tool list); trigger precision good (hook matchers); environment fit good (multi-platform configs). Deductions: some platform support incomplete (e.g., Cursor pending review), environment fit has limitations.
Evidence shows: information architecture clear (README, docs); install notes detailed; naming stable (ctx_* tools); examples and FAQ provided; known limitations documented (e.g., Cursor limitations); license clear (ELv2); version and changelog provided (package.json version) but no standalone CHANGELOG; maintenance responsibility clear (author, repo). Deductions: no standalone CHANGELOG, maintenance responsibility not fully explicit.
Evidence shows: output usability high (tools return structured results); marginal value high (98% context savings); cost-benefit reasonable (free open source). Deductions: no independent cost analysis, but overall reasonable.
Evidence shows: claims traceable (README references issues, docs); cross-source corroboration limited (only within repo); fact-inference separation good (README distinguishes problem and solution). Deductions: cross-source corroboration insufficient.
- Publisher unverified, identity unknown.
- Dependency security not audited, recommend checking dependency vulnerabilities.
- Sensitive data (e.g., session data) not explicitly encrypted, recommend encryption at rest.
- Some platform support incomplete (e.g., Cursor pending review), confirm before install.
- No standalone CHANGELOG, version change history incomplete.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Context-savings reporting + FinOps accuracy This release aligns context-savings reporting between the local ctx stats view and the Insight platform, and corrects per-turn cost attribution. Improvements - The local "Where you are now" savings bar now reflects the whole live conversation window — the main session plus the sub-agent and sandbox sessions it spawns — rather than a single session id. - The kept-out ratio is reported to one decimal, so a genuine 99.9% window is no longer rounded up to a misleading 100%. Fixes …View on GitHub ↗ -
Release notes excerpt
FinOps accuracy and context-savings reporting Follow-up to v1.0.167's per-turn cost capture. This release corrects how savings and cost are measured and reported. Fixes - Context-savings bar accuracy. ctx stats previously rendered "With context-mode: 1 B / 100% kept out" on tool-heavy sessions. The "With context-mode" figure now reflects the real bytes the model paid to access kept-out content (ctx_search + ctx_fetch_and_index returns), not sandbox compute output, so the kept-out ratio is honest. …View on GitHub ↗ -
Release notes excerpt
Per-turn token, cost, and savings capture (FinOps) Events now carry real per-turn token usage, model id, and cost_usd, replacing the flat per-event cost proxy. Engineering leaders can see actual AI spend per model, how much context-mode saved, and net/ROI. Highlights - Real per-model pricing catalog (63 curated models across Anthropic, OpenAI, Google, and other vendors) behind a small no-regex lookup module. Non-Claude models are now priced from their own rates instead of defaulting to Claude pricing. …View on GitHub ↗
FAQ
Is Context Mode free?
Will using sandbox tools limit functionality?
Does Context Mode collect my data?
How do I uninstall?
/plugin to uninstall; for others, remove the MCP config, hooks file, and the global npm package.