RELATED 01
LeanCTX
Local context layer for coding agents: cached, compressed file reads, shell output and session memory
3.9kGitHub stars
1.2k/wknpm downloads
58popularity score
Context Mode
Keeps large tool output out of a coding agent's context by running it in a sandbox and indexing it locally.
By Mert Köseoğlu (individual) JavaScript Local · stdio Developer toolsKnowledge and memory
103 popularity score ★ 34k ↓ 67k/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
FirstTerminal
npm i -g context-modeClaude CodeTerminal
claude mcp add context-mode -- context-mode server --agent '<AGENT_ID>'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"context-mode": {
"command": "context-mode",
"args": [
"server",
"--agent",
"<AGENT_ID>"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"context-mode": {
"command": "context-mode",
"args": [
"server",
"--agent",
"<AGENT_ID>"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"context-mode": {
"type": "stdio",
"command": "context-mode",
"args": [
"server",
"--agent",
"<AGENT_ID>"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.context-mode]
command = "context-mode"
args = ["server", "--agent", "<AGENT_ID>"]Gemini CLITerminal
gemini mcp add --scope user context-mode context-mode -- server --agent '<AGENT_ID>'What it does
Context Mode sits between a coding agent and the big outputs it would otherwise read whole: files, logs, command output and web pages. The agent sends a short script to ctx_execute, the script reads the data in a subprocess, and only what it prints comes back into the conversation. Larger results go into a per-project SQLite database (context.db under ~/.context-mode), split into chunks and searchable with FTS5, so the agent can pull back just the parts it asks for with ctx_search.
On agents with hooks, the plugin also steers the agent toward these tools. A PreToolUse hook stops a full-file Read over 16,384 bytes, WebFetch and curl calls and similar dumps, and names the ctx_* call to use instead. The hooks keep a journal of prompts, edits, commands and errors, and after compaction ctx_resume hands back a state block of at most 2,048 bytes.
The README covers 10 agents: Claude Code, Codex, Gemini CLI, Qwen Code, Pi, OpenCode, Copilot CLI, Kiro, VS Code and ZCode. Each has its own install command, and `context-mode setup` after a global npm install configures any of them. The code at this release names five languages for ctx_execute (shell, powershell, javascript, typescript and python) and also accepts any other runtime on PATH. The MCP server needs an --agent argument to find the project, except under Claude Code, where it reads CLAUDE_PROJECT_DIR.
The README also advertises Context Mode Gateway, a separate hosted service with its own account and subscription that proxies requests to Anthropic and OpenAI. That is not part of this package. The license is Elastic License 2.0, which is source-available and bars offering it to others as a hosted service.
What it needs
| Runtime | Node.js 24.15.0+ |
|---|---|
| Runs on | macOS, Windows, Linux |
| Also |
|
Limits
- Limit The server resolves its project from --agent <id>, or from CLAUDE_PROJECT_DIR under Claude Code. Without either, tool calls that need a project fail with NO_PROJECT.
- Size cap ctx_execute runs for at most 600,000 ms, which is both the default and the cap, then stops the whole process group.
- Size cap Indexed output is split into chunks of at most 4,096 bytes, and a ctx_resume reply is at most 2,048 bytes.
- Not covered ctx_search and ctx_resume read one project's local database. Search across sessions and agents is a Gateway feature, a paid hosted service.
- Limit The routing hooks only work on agents that load them. Over plain MCP the agent has to choose the ctx_* tools itself.
Who it suits
Suits developers on one of the 10 supported agents who keep hitting context limits from long logs, big files or fetched docs, and who want everything stored on their own machine. It needs Node 24.15 or later, which is newer than many machines carry. Since ctx_execute runs any code as your user, it fits setups where the agent's own permission prompts stay on. Teams that want memory shared across machines and agents are pointed by the makers to their hosted Gateway, which is a paid service that sees your requests.
Tools 9
3 only read, 5 change things, 1 can delete or overwrite.
ctx_executechanges- Run a script or shell command in a subprocess and return only what it prints.
ctx_batchchanges- Run several commands, index their output and search it with several queries in one call.
ctx_indexchanges- Add a file, a block of text or a fetched URL to the project's local search index.
ctx_search- Search the local index and return the matching chunks.
ctx_resume- Return the saved session state block, or one full journal row by its seq number.
ctx_stats- Report how much output was kept out of the context, for this session and overall.
ctx_doctorchanges- Check the install and print PASS or a fix command for each check.
ctx_upgradechanges- Install, upgrade or uninstall the plugin and replace older entries.
ctx_purgedeletes- Delete indexed data for one session, one source or the whole project.