LeanCTX

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

Connect your client

Local (npm)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal
claude mcp add leanctx -- npx -y lean-ctx-bin
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "leanctx": {
      "command": "npx",
      "args": [
        "-y",
        "lean-ctx-bin"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "leanctx": {
      "command": "npx",
      "args": [
        "-y",
        "lean-ctx-bin"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "leanctx": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "lean-ctx-bin"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.leanctx]
command = "npx"
args = ["-y", "lean-ctx-bin"]
Gemini CLITerminal
gemini mcp add --scope user leanctx npx -- -y lean-ctx-bin
Local (from source)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

FirstTerminal
cargo install lean-ctx
Claude CodeTerminal
claude mcp add leanctx -- lean-ctx
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "leanctx": {
      "command": "lean-ctx",
      "args": []
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "leanctx": {
      "command": "lean-ctx",
      "args": []
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "leanctx": {
      "type": "stdio",
      "command": "lean-ctx",
      "args": []
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.leanctx]
command = "lean-ctx"
args = []
Gemini CLITerminal
gemini mcp add --scope user leanctx lean-ctx

Settings 12

LEAN_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. For ctx_shell.
LEAN_CTX_SHELL_ALLOW_INLINE_SCRIPTS Optional: Lets shell commands run inline scripts such as python3 -c. For ctx_shell.
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. Default ~/.local/share/lean-ctx.
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). Default projects.
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.

What it does

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.

What it needs

RuntimeNode.js 16+A prebuilt binary
Runs onmacOS, 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).

Limits

  • Early release Multi-agent handoff (`ctx_agent`, `ctx_handoff`), context packages, Time Machine snapshots and addons are labelled research or experimental by the makers.
  • Limit Savings shown by Shadow Mode are simulated, not measured, and say nothing about answer quality.
  • Limit The makers say gains shrink to break-even in small repositories or when raw logs are always needed.
  • Limit Shortened output can drop detail. `--raw` or the tools' `raw` parameter returns it in full.
  • Not covered More than 30 tools were removed in the focus release, among them `ctx_retrieve` and `ctx_refactor`. Most now answer with their replacement or a retirement note.
  • Not covered No refactoring tool of its own: renames and other write refactorings are left to the host, with `ctx_callgraph` for references.
  • Limit The npm postinstall also adds LeanCTX Cockpit, a local web UI under its own EULA that is not open source. `LEAN_CTX_NO_COCKPIT=1` skips it.
  • Platform Prebuilt binaries cover Linux x86_64 and aarch64, macOS and Windows x86_64 only. Older Windows releases may be unsigned.
  • Limit The licence is mixed (LICENSE.md): the core is Apache-2.0 while some modules carry other terms.

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).

Who it suits

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.

Tools 55

25 only read, 26 change things, 4 can delete or overwrite. A ? marks an optional parameter.

ctx_read
Reads one file or a batch in a chosen mode, cached so an unchanged re-read returns a short referenceaggressiveness?: anyengine_interface?: anyfresh?: anylimit?: anymode?: anyoffset?: anypath?: anypaths?: anyprotect?: anyraw?: anystart_line?: anysymbol?: any
ctx_delta
Returns only the lines that changed since the file was last readpath: any
ctx_outline
Lists the symbols of a file or folder, parsed by syntaxpath: anyformat?: anykind?: anymatch?: any
ctx_search
Searches code by regex, meaning or symbol name, or finds related filesaction?: anyanchored?: anyexclude?: anyexclude_pattern?: anyfile?: anyfile_path?: anyhandle?: anyinclude?: anykind?: anyline?: anymax_results?: anymode?: anyname?: anypath?: anypaths?: anypattern?: anyqueries?: anyquery?: anytop_k?: any
ctx_glob
Finds files by glob pattern across one or more roots, honouring .gitignorepattern: anyignore_gitignore?: anymax_results?: anypath?: anypaths?: any
ctx_tree
Shows a short directory tree with file countsdepth?: anypath?: anypaths?: anyrespect_gitignore?: anyshow_hidden?: any
ctx_compose
Picks and ranks the files and source a task needs, within the turn budgettask: anypath?: anytask_aware?: any
ctx_patch changes
Edits files by hash-anchored line ranges from an anchored read, or creates a filedry_run?: anyend_hash?: anyend_line?: anyfind?: anyhash?: anyline?: anyname?: anynew_text?: anyold_text?: anyop?: anyops?: anypath?: anyreplace?: anystart_hash?: anystart_line?: any
ctx_edit changes
Older search-and-replace edit with guards against concurrent changesnew_string: anypath: anycreate?: anyold_string?: anyreplace_all?: any
ctx_shell deletes
Runs a shell command and shortens its output; can run in the backgroundbackground_action?: anycommand?: anycwd?: anyenv?: anyinline?: anyjob_id?: anyraw?: anyrun_in_background?: anytimeout_ms?: any
shell deletes
Same as ctx_shell, under the name some clients expectcommand: anycwd?: anyraw?: any
ctx_execute deletes
Runs code in a sandbox in one of 11 languages, as a snippet, batch or fileaction?: anycode?: anyintent?: anyitems?: anylanguage?: anypath?: anytimeout?: any
ctx_expand
Brings back tool output that was archived or held back, in full or by rangeaction?: anyend_line?: anyhead?: anyid?: anyjson_keys?: anyjson_path?: anyquery?: anysearch?: anysession_id?: anystart_line?: anytail?: any
ctx_url_read
Fetches a web page, PDF, feed or YouTube transcript as shortened text, with SSRF checksurl: anymax_items?: anymax_tokens?: anymode?: anyquery?: anytimeout_secs?: any
ctx_git_read
Reads a remote git repository through a cached shallow cloneurl: anymax_tokens?: anymode?: anypath?: anyquery?: anyref?: anytimeout_secs?: any
ctx_multi_repo changes
Registers several repositories and searches across themaction: anyalias?: anymax_results?: anymode?: anypath?: anyquery?: anyroots?: any
ctx_session changes
Keeps session notes: tasks, findings, decisions, handoffs and restoresaction: anykeep_recent_turns?: anysession_id?: anytag?: anyvalue?: any
ctx_knowledge changes
Stores and recalls project knowledge that lasts across sessionsaction: anyanchors?: anyas_of?: anycategory?: anycommands?: anyconfidence?: anycontent?: anydry_run?: anyevidence?: anyexamples?: anyformat?: anykey?: anylimit?: anymerge?: anymode?: anypath?: anypattern_type?: anyquery?: anyrefs?: anyresolution?: any
ctx_memory changes
Keeps facts shared between agents, with deduplication and pruningaction: anyagent?: anycategory?: anycontent?: anylimit?: anymax_age_seconds?: anymax_entries?: anyquery?: any
ctx_compress changes
Shrinks the read cache to free token budgetinclude_signatures?: any
ctx_compress_memory changes
Rewrites a memory or rules file such as CLAUDE.md in shorter form. An .original.md copy is keptpath: any
ctx_transcript_compact
Compacts an OpenAI-format message list in a repeatable waymessages: anyfocus_topic?: anyfresh_tail_tokens?: anyprotect_min_messages?: any
ctx_artifacts changes
Indexes and searches registered context artifacts with BM25action: anyformat?: anyname?: anyproject_root?: anyquery?: anytop_k?: any
ctx_index changes
Shows or builds the code index and explains why a file is not indexedaction: anypath?: anyproject_root?: any
ctx_checkpoint deletes
Snapshots the agent's changes in a separate shadow git history and can restore themaction?: anyfrom?: anylimit?: anymessage?: anypath?: anyref?: anyto?: any
ctx_package changes
Saves and resumes bundles of session, summary and knowledge for a handoffaction?: anydescription?: anypath?: any
ctx_pack changes
Builds, installs, exports and imports context packages, including PR packsaction: anyapply?: anyauthor?: anybase?: anycategories?: anydepth?: anydescription?: anydiff?: anyemit?: anyenable?: anyfacts?: anyfile?: anyformat?: anyignore?: anyinclude?: anyintent?: anykeys?: anyknowledge_limit?: anylayers?: anylevel?: any
ctx_graph
Answers dependency questions from a file-level graph: impact, paths, diagrams, diffsaction: anydepth?: anyformat?: anykind?: anypath?: anyproject_root?: anysince?: anyto?: any
ctx_callgraph
Lists callers and callees of one symbol, traces call paths and rates change riskaction: anydepth?: anyfile?: anyfrom?: anysymbol?: anyto?: any
ctx_control changes
Applies reversible overlays to the delivered context: exclude, pin, evict, prioritiseaction: anyreason?: anyscope?: anytarget?: anytargets?: anyvalue?: any
ctx_context
Shows the session's cached and seen files and its state
ctx_preload
Caches the files relevant to a task and returns a short summarytask: anypath?: any
ctx_prefetch
Warms the cache with the files a change is likely to touchbudget_tokens?: anychanged_files?: anymax_files?: anyroot?: anytask?: any
ctx_dedup changes
Finds repeated content across file reads and can apply the cutsaction?: any
ctx_verify
Reports tool-call statistics and context proof claimsaction?: anyformat?: any
ctx_proof changes
Exports a machine-readable context proof, optionally as a fileaction: anyfilename?: anyformat?: anymax_evidence?: anymax_ledger_files?: anyproject_root?: anywrite?: any
ctx_metrics
Shows session token counts and cache hit rates
ctx_radar
Breaks down where the context budget goes: prompt, messages, tools, reads, shellformat?: any
ctx_cost changes
Attributes local token cost per agent and tool; can reset the countsaction?: anyagent_id?: anylimit?: any
ctx_gain
Reports local context savings, scores and a summary over a periodaction?: anylimit?: anymodel?: anyperiod?: any
ctx_heatmap
Shows which files are read mostaction?: anypath?: any
ctx_feedback changes
Records and reports model token and latency figuresaction?: anyagent_id?: anyintent?: anylatency_ms?: anylimit?: anyllm_input_tokens?: anyllm_output_tokens?: anymodel?: anynote?: any
ctx_discover
Lists shell commands that run without lean-ctx compression yetlimit?: any
ctx_provider
Queries GitHub, GitLab, Jira, Postgres, MCP bridges or a custom REST sourceaction: anyid?: anyiid?: anylabels?: anylimit?: anymode?: anyproject?: anyprovider?: anyquery?: anyresource?: anystate?: anystatus?: any
ctx_tools changes
Finds and calls tools on downstream MCP serversaction?: anyarguments?: anyquery?: anytool?: any
ctx_call changes
Calls any registered tool by name, including ones the profile hidesname: anyarguments?: any
ctx_discover_tools
Searches all tools by keywordquery?: any
ctx_load_tools changes
Loads or unloads tool categories while runningaction: anycategory?: any
ctx_tasks changes
Lists, claims, updates and submits the project's Hive tasks, since v3.12.1action: anyacceptance?: anyevidence?: anygoal?: anymine?: anyminutes?: anynumber?: anyoutcome?: anyreason?: anyrole?: anystate?: anysummary?: anytitle?: anytokens?: anyverdict?: any
ctx_doc changes
Reads, writes and edits project documentation pages in the linked Hive vault, bound to codeaction: anyanchors?: anycontent?: anyfind?: anyoutline?: anyquery?: anyreplace?: anysection?: anyslug?: anystatus?: anytype?: any
ctx_work_graph changes
Keeps a local work graph that coordinates several agents on one projectaction: 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?: any
ctx_agent changes
Experimental local multi-agent tool, callable but not listed
ctx_share changes
Local collaboration compatibility tool, callable but not listed
ctx_handoff changes
Experimental handoff between agents, callable but not listed
ctx_shape
Hook for host integrations, callable but not listed

Similar servers