Context-Mode: AI Coding Agent Context Window Optimization That Cuts Tool Output 98%

If you have spent any time with Claude Code, Codex, Cursor or any other agentic coding assistant this year, you know the failure mode: forty minutes into a productive session, the agent starts forgetting which files it was editing, re-reading code it already read, and asking you to re-explain the plan. That is AI coding agent context window optimization territory — and one GitHub repository, mksglu/context-mode, has quietly gathered more than 30,000 stars by attacking the problem at its most expensive point: tool output. Its headline claim is a 98% reduction in the context consumed by tool calls, and the mechanism behind it is genuinely interesting even if you never install the thing.

In this deep dive we cover what Context-Mode is, how its MCP sandbox actually works, the real install commands, the benchmark numbers behind the 98% claim, why it is trending, and — because we run AI-assisted development workflows for clients every day — the honest limitations nobody puts in the README hero section.

What Context-Mode actually is

Context-Mode is an MCP (Model Context Protocol) server, written in TypeScript, that sits between your coding agent and the messy real world. Instead of letting every tool call dump its raw output straight into the model’s context window, Context-Mode routes data-heavy operations through sandboxed tools that execute in an isolated subprocess and return only a compact summary. The README’s motivating example: a Playwright snapshot that normally costs 56 KB of context becomes 299 bytes. Twenty GitHub issues: 59 KB down to 1.1 KB. An access log of 500 requests: 45 KB down to 155 bytes.

The project is maintained by mksglu, was first pushed in February 2026, and was still being committed to on the day we researched this (16 October 2026) — always a good sign for a fast-moving dependency. It hit #1 on Hacker News with 570+ points, and its 2,100+ forks suggest it is being actively evaluated, not just starred and forgotten.

What it can do: 11 MCP tools, four pillars

Context-Mode ships 11 MCP tools in two groups. Six sandbox tools do the actual work:

• ctx_execute / ctx_execute_file / ctx_batch_execute — run code (JavaScript, Python, shell) in the sandbox and get back only the result, not the transcript
• ctx_index / ctx_search — index local files or directories into a persistent full-text knowledge base and search them later
• ctx_fetch_and_index — fetch a URL, index it, and return a summary

Five meta tools keep the system observable:

• ctx_stats — per-tool token savings, so you can see the economy working in real time
• ctx_doctor — diagnostics for runtimes, hooks, the search index and plugin registration
• ctx_upgrade / ctx_purge — update the install, or permanently delete all indexed content
• ctx_insight — opens a hosted analytics dashboard for org-level AI engineering teams

The README frames the design around four pillars: context saving (sandbox tools keep raw data out), session continuity (every file edit, git operation, task, error and user decision is tracked in SQLite, then indexed with FTS5 and retrieved by BM25 search only when relevant), “think in code” (the agent programs the analysis instead of computing it — one ctx_execute script replacing 47 read calls), and no prose-style enforcement (it routes where data goes but never dictates how the model writes its answer).

How it works under the hood

The core idea is simple and well executed. Raw data is processed in a sandboxed subprocess at the MCP protocol layer — web pages, API responses, file analysis, Playwright snapshots, log files — and the context window only ever sees the digest. The README’s canonical example:

// Before: 47 × Read() = 700 KB. After: 1 × ctx_execute() = 3.6 KB.
ctx_execute(“javascript”, … const files = fs.readdirSync(‘src’); // count lines, log only totals …)

On hook-capable platforms (Claude Code is the flagship), the install registers hooks for PreToolUse, PostToolUse, UserPromptSubmit, PreCompact and SessionStart, so routing is enforced automatically — the model is nudged toward the sandbox tools without you writing routing instructions into your project. On platforms without hooks, you copy a routing file (e.g. AGENTS.md, GEMINI.md, or a Cursor .mdc rule) and rely on the model to follow it. The README is admirably honest about the difference: roughly 98% savings with automatic hook routing versus about 60% with routing files alone.

The knowledge base is also properly engineered rather than bolted on: Reciprocal Rank Fusion for ranking, proximity reranking, fuzzy correction, smart snippets, a TTL cache and progressive throttling. Session continuity is the sleeper feature — when your conversation compacts, the model pulls back exactly the relevant events (files touched, tasks in progress, decisions made) instead of re-prompting you for everything it forgot.

Why it is trending right now

Context exhaustion is the number-one complaint about coding agents in 2026, and Context-Mode attacks it from a direction most optimisation advice ignores. The usual guidance — “write tighter prompts”, “use smaller models” — treats the model’s output as the problem. Context-Mode’s insight is that the input side is where sessions bleed: the agent burns context on filler it never needed to see. A full-session benchmark in the repo claims 315 KB of raw output compressing to 5.4 KB, stretching a session from roughly 30 minutes of useful work to around 3 hours.

Timing matters too. It supports 17 agent platforms — Claude Code, Gemini CLI, Codex CLI, Cursor, both Copilot flavours, OpenCode, OpenClaw, Kiro, Zed, Antigravity, Pi and several more — which means teams are not locked into one vendor’s agent to use it. And the architecture choice is philosophically fashionable: everything runs locally, no telemetry, no cloud sync, no account. The SQLite databases live in your home directory. In a year when every AI tool wants your data in its cloud, a privacy-first design that still works is genuinely refreshing.

From our experience: the honest limitations

We build AI-assisted development workflows at MTD Technologies, so here is the practitioner’s read — the stuff that matters before you roll this out to a team:

• The 98% is a vendor benchmark on tool-output-heavy workflows. It is measured on tasks like scraping, log analysis and repo research — exactly the tasks where raw output is enormous. If your agents mostly edit a handful of files, your savings will be smaller. Run ctx-stats after a real week of work and trust your own number.
• Routing compliance drops without hooks. 98% with automatic hook enforcement, ~60% with a routing file the model merely reads. On Cursor specifically, the README documents a known limitation: Cursor accepts additional_context in hook responses but does not surface it to the model. Choose your platform accordingly.
• The licence is source-available, not open source. Context-Mode is licensed under the Elastic License 2.0. That is fine for internal development use, but ELv2 restricts offering the software as a hosted service to third parties. If you plan to embed it in a commercial product or a managed agent platform, read the licence text first — do not assume “on GitHub” means “free to resell”.
• It does not enlarge your context window. The model still has the same window; Context-Mode just stops tool output from filling it. Reasoning-heavy tasks with genuinely large working sets still hit the wall.
• Session data persists locally — manage it. Indexed content and session events live in SQLite under your home directory. On shared machines or contractor laptops, ctx_purge is your friend, and be deliberate about what you ctx_index.

None of these are dealbreakers — they are the normal shape of a serious dev tool. What we like is that most of them are documented in the repo itself rather than discovered in production.

Security note: sandbox permissions inherit your rules

One design decision deserves explicit praise. Context-Mode extends your existing permission rules into the MCP sandbox: if you deny Bash(sudo *) or Read(.env) in your agent’s settings, those denies apply inside ctx_execute too — deny always wins over allow, and chained commands are split and checked separately. All platforms read the policy from Claude Code’s settings format, which keeps one policy file for mixed-agent teams. The responsible-use caveat: a sandbox is not a security audit. It reduces the blast radius of a rogue tool call, but your permission policy is still the actual security boundary — keep it tight, especially Read(**/.env*).

Getting started in five steps

1. Install. For Claude Code (v1.0.33+): run /plugin marketplace add mksglu/context-mode then /plugin install context-mode@context-mode, and restart. For everything else: npm install -g context-mode (Node 22.5+) and register it as an MCP server, e.g. claude mcp add context-mode -- npx -y context-mode.
2. Verify. Run /context-mode:ctx-doctor (or type ctx doctor on non-Claude platforms). Every check should pass — it validates runtimes, hooks, the FTS5 index and plugin registration.
3. Try a data-heavy task. Ask the agent to research a repo’s architecture or analyse a large log file, then run ctx-stats to see the per-tool savings. The repo’s own “Try it” prompts are good first runs.
4. Set permissions. Add deny rules for secrets and destructive commands in your agent settings — they propagate into the sandbox automatically.
5. Measure for a week. Compare your ctx-stats totals against your API bill or session lengths before rolling it out team-wide. The business case writes itself if the numbers hold on your workload.

Frequently asked questions

Does Context-Mode make the context window bigger?

No. The model’s context window stays exactly the same size. Context-Mode stops tool output — snapshots, logs, API responses, file dumps — from filling it, by processing raw data in a sandboxed subprocess and returning only compact summaries. Your window goes further because less of it is wasted.

Is Context-Mode really free and open source?

It is free to install via npm and the source is on GitHub, but the licence is the Elastic License 2.0 — source-available rather than OSI-approved open source. Internal and development use is fine; offering it as a hosted service to third parties is restricted. Check the licence before embedding it in a commercial product.

Which AI coding agents does it work with?

Seventeen platforms are documented, including Claude Code, Gemini CLI, Codex CLI, Cursor, VS Code and JetBrains Copilot, the GitHub Copilot CLI, OpenCode, OpenClaw, Kiro, Zed, Antigravity and the Pi coding agent. Hook-capable platforms get automatic routing enforcement (~98% savings); the rest use a routing file with roughly 60% compliance.

Will it change how my agent writes answers?

No — deliberately. Context-Mode’s routing block only controls where data goes, never how the model writes. The maintainers cite benchmark evidence that aggressive brevity prompts can degrade coding and reasoning quality, so tone and completeness stay under your control (or your own CLAUDE.md / AGENTS.md).

Does it send my code to the cloud?

No. There is no telemetry, no cloud sync, no usage tracking and no account. Session data and the search index live in local SQLite databases in your home directory, and ctx_purge deletes them permanently when you are done.

Context exhaustion is the tax every agentic coding workflow pays, and most teams pay it in API bills and stalled sessions without realising how much of it is just tool output nobody needed to see. Context-Mode is one of the more serious attempts to fix the input side of the problem — 30,000 stars, a #1 Hacker News launch, and honest documentation of its own limits. If your team lives in coding agents all day, it is worth an afternoon of evaluation: install it, run your real workload, and let ctx-stats tell you whether the 98% holds for you. And if you need help wiring AI-assisted development into your team’s workflow — from agent setup to AI integration and automation — talk to us. This is what we do: check our AI tools directory for more practitioner-reviewed tooling.