Context Mode
Keeps large tool output out of a coding agent's context by running it in a sandbox and indexing it locally.
Local context layer for coding agents: cached, compressed file reads, shell output and session memory
By Yves Gugger (individual) Rust Local · stdio Developer toolsKnowledge and memory
58 popularity score ★ 3.9k ↓ 1.2k/wk
Opens the app, which asks before it adds the server.
claude mcp add leanctx -- npx -y lean-ctx-bin{
"mcpServers": {
"leanctx": {
"command": "npx",
"args": [
"-y",
"lean-ctx-bin"
]
}
}
}{
"mcpServers": {
"leanctx": {
"command": "npx",
"args": [
"-y",
"lean-ctx-bin"
]
}
}
}{
"servers": {
"leanctx": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"lean-ctx-bin"
]
}
}
}[mcp_servers.leanctx]
command = "npx"
args = ["-y", "lean-ctx-bin"]gemini mcp add --scope user leanctx npx -- -y lean-ctx-binOpens the app, which asks before it adds the server.
cargo install lean-ctxclaude mcp add leanctx -- lean-ctx{
"mcpServers": {
"leanctx": {
"command": "lean-ctx",
"args": []
}
}
}{
"mcpServers": {
"leanctx": {
"command": "lean-ctx",
"args": []
}
}
}{
"servers": {
"leanctx": {
"type": "stdio",
"command": "lean-ctx",
"args": []
}
}
}[mcp_servers.leanctx]
command = "lean-ctx"
args = []gemini mcp add --scope user leanctx lean-ctxLEAN_CTX_TOOL_PROFILE |
Optional: Tool set to advertise: minimal, standard, power or auto. Overrides the config file. |
|---|---|
LEAN_CTX_SHELL_ALLOW_WRITES |
Optional: 1, true, yes or on lets shell commands write files by redirect. Command gating still applies. |
LEAN_CTX_SHELL_ALLOW_INLINE_SCRIPTS |
Optional: Lets shell commands run inline scripts such as python3 -c. |
LEAN_CTX_DISABLED_TOOLS |
Optional: Tools to switch off. Overrides disabled_tools in the config file. |
LEAN_CTX_NO_UPDATE_CHECK |
Optional: Any value turns off the daily update check. |
LEAN_CTX_DATA_DIR |
Optional: Data directory for sessions, knowledge and caches. |
LEAN_CTX_MCP_IDLE_EXIT_MINUTES |
Optional: Minutes of idleness after which the stdio server exits. 0 means never. |
| Set together: path jail | |
LEAN_CTX_PATH_JAIL_SCOPE |
Optional: File boundary: projects (folders with a project marker under home), home, or project (the session's project only). |
LEAN_CTX_ALLOW_PATH |
Optional: Extra directories the file tools may read and write, as a path list. |
LEAN_CTX_EXTRA_ROOTS |
Optional: Additional workspace roots added to the allowed paths, as a path list. |
LEAN_CTX_READ_ONLY_ROOTS |
Optional: Directories that are readable but never writable. |
LEAN_CTX_ALLOW_IDE_DIRS |
Optional: Set to 1 to let the tools read editor config folders. |
LeanCTX (command `lean-ctx`) is a Rust program that sits between a coding assistant and the project it works on. Run as an MCP server over stdio, it offers `ctx_*` tools meant to stand in for an editor's own read, search and shell tools. `ctx_read` reads files in modes such as anchored, signatures, map, line ranges or a diff since the last read, and answers a repeat read of an unchanged file with a short reference. `ctx_shell` runs commands and shortens their output. `ctx_search` covers regex and semantic search. `ctx_compose` picks the files a task needs within the turn budget.
Code questions go to `ctx_graph` (file dependencies and impact) and `ctx_callgraph` (callers and callees of a symbol). Edits go through `ctx_patch`, which works on hash-anchored line ranges, or the older `ctx_edit`. It also keeps local state across chats: session notes, a project knowledge store and checkpoints of the agent's own edits in a shadow git history kept apart from the project's `.git`. Other tools fetch web pages and transcripts, read remote repositories through a shallow clone, run code in a sandbox, query issue trackers or Postgres, and forward calls to other MCP servers.
The registry in the source (rust/crates/lean-ctx-server/src/server/registry.rs) registers 55 tools. 51 are advertised. Four more (`ctx_agent`, `ctx_share`, `ctx_handoff`, `ctx_shape`) stay callable but are listed on no profile. Clients see 5 tools with the `minimal` profile, 15 with `standard` and all 51 with `power`, chosen with `lean-ctx tools` or `LEAN_CTX_TOOL_PROFILE`. With no profile set, an install that predates profiles gets `power`. A 2026 focus release removed more than 30 older tools, among them `ctx_retrieve`, `ctx_refactor`, `ctx_fill` and `ctx_architecture`. Calling most of them now returns the tool to use instead or a note that it was retired.
| Runtime | Node.js 16+A prebuilt binary |
|---|---|
| Runs on | macOS, Windows, Linux |
The npm package `lean-ctx-bin` downloads the `lean-ctx` binary for Linux (x86_64, aarch64), macOS (Intel or Apple Silicon) or Windows x86_64 at install. The binary can also come from Homebrew (`brew tap yvgude/lean-ctx && brew install lean-ctx`), the install script, or `cargo install lean-ctx` with a Rust toolchain. No account or key for the MCP tools. `ctx_provider` needs the token of each service it reaches (GitHub, GitLab, Jira, Postgres).
Several parts are labelled experimental or research by the makers: multi-agent handoff (`ctx_agent`, `ctx_handoff`), context packages, snapshots, the team server and addons; there is no hosted service. Savings reports from Shadow Mode are simulated, not measured, and say nothing about answer quality. The makers say gains shrink to break-even in small repos or with fresh sessions. Compressed output can drop detail; `--raw` or `LEAN_CTX_RAW=1` returns it unshortened. Older Windows releases may be unsigned. Licence is mixed: the core is Apache-2.0, but some v4 modules use commercial source-visible terms (LICENSE.md).
Suits developers who run Claude Code, Cursor, Codex or a similar agent on medium or large repositories with heavy shell use and want fewer tokens spent on repeat reads and noisy command output, all processed on their own machine. The `standard` profile replaces much of an editor's native reading and editing, so it fits people willing to let one server own file and shell access. Pick something narrower if you only need plain file access, work in small repos or always need raw logs, or if you cannot accept a server that writes files and runs commands inside your projects.
25 only read, 26 change things, 4 can delete or overwrite. A ? marks an optional parameter.
ctx_readaggressiveness?: anyengine_interface?: anyfresh?: anylimit?: anymode?: anyoffset?: anypath?: anypaths?: anyprotect?: anyraw?: anystart_line?: anysymbol?: anyctx_deltapath: anyctx_outlinepath: anyformat?: anykind?: anymatch?: anyctx_searchaction?: anyanchored?: anyexclude?: anyexclude_pattern?: anyfile?: anyfile_path?: anyhandle?: anyinclude?: anykind?: anyline?: anymax_results?: anymode?: anyname?: anypath?: anypaths?: anypattern?: anyqueries?: anyquery?: anytop_k?: anyctx_globpattern: anyignore_gitignore?: anymax_results?: anypath?: anypaths?: anyctx_treedepth?: anypath?: anypaths?: anyrespect_gitignore?: anyshow_hidden?: anyctx_composetask: anypath?: anytask_aware?: anyctx_patch changesdry_run?: anyend_hash?: anyend_line?: anyfind?: anyhash?: anyline?: anyname?: anynew_text?: anyold_text?: anyop?: anyops?: anypath?: anyreplace?: anystart_hash?: anystart_line?: anyctx_edit changesnew_string: anypath: anycreate?: anyold_string?: anyreplace_all?: anyctx_shell deletesbackground_action?: anycommand?: anycwd?: anyenv?: anyinline?: anyjob_id?: anyraw?: anyrun_in_background?: anytimeout_ms?: anyshell deletescommand: anycwd?: anyraw?: anyctx_execute deletesaction?: anycode?: anyintent?: anyitems?: anylanguage?: anypath?: anytimeout?: anyctx_expandaction?: anyend_line?: anyhead?: anyid?: anyjson_keys?: anyjson_path?: anyquery?: anysearch?: anysession_id?: anystart_line?: anytail?: anyctx_url_readurl: anymax_items?: anymax_tokens?: anymode?: anyquery?: anytimeout_secs?: anyctx_git_readurl: anymax_tokens?: anymode?: anypath?: anyquery?: anyref?: anytimeout_secs?: anyctx_multi_repo changesaction: anyalias?: anymax_results?: anymode?: anypath?: anyquery?: anyroots?: anyctx_session changesaction: anykeep_recent_turns?: anysession_id?: anytag?: anyvalue?: anyctx_knowledge changesaction: anyanchors?: anyas_of?: anycategory?: anycommands?: anyconfidence?: anycontent?: anydry_run?: anyevidence?: anyexamples?: anyformat?: anykey?: anylimit?: anymerge?: anymode?: anypath?: anypattern_type?: anyquery?: anyrefs?: anyresolution?: anyctx_memory changesaction: anyagent?: anycategory?: anycontent?: anylimit?: anymax_age_seconds?: anymax_entries?: anyquery?: anyctx_compress changesinclude_signatures?: anyctx_compress_memory changespath: anyctx_transcript_compactmessages: anyfocus_topic?: anyfresh_tail_tokens?: anyprotect_min_messages?: anyctx_artifacts changesaction: anyformat?: anyname?: anyproject_root?: anyquery?: anytop_k?: anyctx_index changesaction: anypath?: anyproject_root?: anyctx_checkpoint deletesaction?: anyfrom?: anylimit?: anymessage?: anypath?: anyref?: anyto?: anyctx_package changesaction?: anydescription?: anypath?: anyctx_pack changesaction: anyapply?: anyauthor?: anybase?: anycategories?: anydepth?: anydescription?: anydiff?: anyemit?: anyenable?: anyfacts?: anyfile?: anyformat?: anyignore?: anyinclude?: anyintent?: anykeys?: anyknowledge_limit?: anylayers?: anylevel?: anyctx_graphaction: anydepth?: anyformat?: anykind?: anypath?: anyproject_root?: anysince?: anyto?: anyctx_callgraphaction: anydepth?: anyfile?: anyfrom?: anysymbol?: anyto?: anyctx_control changesaction: anyreason?: anyscope?: anytarget?: anytargets?: anyvalue?: anyctx_contextctx_preloadtask: anypath?: anyctx_prefetchbudget_tokens?: anychanged_files?: anymax_files?: anyroot?: anytask?: anyctx_dedup changesaction?: anyctx_verifyaction?: anyformat?: anyctx_proof changesaction: anyfilename?: anyformat?: anymax_evidence?: anymax_ledger_files?: anyproject_root?: anywrite?: anyctx_metricsctx_radarformat?: anyctx_cost changesaction?: anyagent_id?: anylimit?: anyctx_gainaction?: anylimit?: anymodel?: anyperiod?: anyctx_heatmapaction?: anypath?: anyctx_feedback changesaction?: anyagent_id?: anyintent?: anylatency_ms?: anylimit?: anyllm_input_tokens?: anyllm_output_tokens?: anymodel?: anynote?: anyctx_discoverlimit?: anyctx_provideraction: anyid?: anyiid?: anylabels?: anylimit?: anymode?: anyproject?: anyprovider?: anyquery?: anyresource?: anystate?: anystatus?: anyctx_tools changesaction?: anyarguments?: anyquery?: anytool?: anyctx_call changesname: anyarguments?: anyctx_discover_toolsquery?: anyctx_load_tools changesaction: anycategory?: anyctx_tasks changesaction: anyacceptance?: anyevidence?: anygoal?: anymine?: anyminutes?: anynumber?: anyoutcome?: anyreason?: anyrole?: anystate?: anysummary?: anytitle?: anytokens?: anyverdict?: anyctx_doc changesaction: anyanchors?: anycontent?: anyfind?: anyoutline?: anyquery?: anyreplace?: anysection?: anyslug?: anystatus?: anytype?: anyctx_work_graph changesaction: anyaccepted_nodes?: anycapsule_ref?: anyclaims?: anycost_micros?: anyexecution_fence?: anyexpected_outcome_ref?: anygraph_id?: anyif_revision?: anymax_concurrency?: anynode_id?: anyoutcome?: anyoutcome_ref?: anyparent_node_id?: anypath_claims?: anypolicy_ref?: anyreceipt_id?: anystop_reason?: anytask_ref?: anytimeout_ms?: anyctx_agent changesctx_share changesctx_handoff changesctx_shape