lean-ctx

LeanCTX — Context Gateway for AI Systems

Control what your AI can see. LeanCTX Engine provides local context selection, supported access and content controls, and evidence of observed context operations for existing agents: Select → Control → Learn → Prove. Learn means local task and knowledge continuity, not model training. Recovery depends on source or archive availability and access permissions. LeanCTX SDK is the separate integration surface for applications.

lean-ctx shapes context before it reaches you: cached reads, compressed shell output, focused search, recovery to exact source. Two rules beat every detail:

1. Fewer round trips beat smaller outputs. One call that answers the question is cheaper than three small ones. Never add a call just to save a few hundred tokens.
2. Never wait by polling. Do not loop sleep + status checks (see below).

Intent → tool

You want to…	Call
Understand how something works (unknown location)	ctx_compose(task) — ranked files + source in one call; use it FIRST instead of search→read→read
Find the exact definition of a symbol	ctx_search(action="symbol", name=…)
Find code by meaning	ctx_search(action="semantic", query=…)
Find a text/regex pattern	ctx_search(pattern=…, path=…)
Who calls X / what calls X makes	`ctx_callgraph(action="callers"
Read a file you will edit	ctx_read(path, mode="anchored") → edit with the host's native edit tool, or ctx_call(name="ctx_patch", arguments={…})
Read a file only for context	`ctx_read(path, mode="signatures"
Re-check a file after editing	ctx_read(path, mode="diff")
Run a command (build, test, git, …)	ctx_shell(command) — output is compressed
List files / directory shape	ctx_glob(pattern) / ctx_tree(path, depth)
Remember across sessions	`ctx_session(action="finding"

Do not read or search through ctx_shell (cat, sed -n, grep, rg): that bypasses the read cache and symbol index. Use ctx_read / ctx_search.

Deferred tools (ToolSearch)

If the host lists lean-ctx tools by name only (Claude Code's ToolSearch), load what the task needs in one call, e.g. select:mcp__lean-ctx__ctx_compose,mcp__lean-ctx__ctx_search,mcp__lean-ctx__ctx_read. Do not fall back to ctx_shell for everything because it happens to be loaded. A tool named here that your tool list lacks (the default profile shows a small core) is still callable: ctx_call(name="ctx_knowledge", arguments={…}). ctx_call(name="ctx_discover_tools", arguments={"query": "…"}) lists all of them.

Long-running commands

• Prefer the host's own background execution that notifies on completion (Claude Code: Bash with run_in_background, or Monitor). Start it, then continue other work or end the turn — you will be told when it finishes.
• ctx_shell(run_in_background=true) jobs do not notify by themselves. Check a job at most once when you actually need its result; never sleep in a loop.

Truncated output

Compressed or archived output ends with a recovery handle. Fetch only the slice you need: ctx_expand(id, search=… | head=N | json_path=…), or ctx_read(path, raw=true) for exact bytes. Do not re-run the command.

Without MCP (CLI)

lean-ctx read <file> -m signatures    # or map | diff | lines:N-M
lean-ctx grep <pattern> [path]
lean-ctx -c "<command>"               # only where the shell is not already wrapped
lean-ctx raw "<command>"              # exact, uncompressed output

Setup

which lean-ctx || curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash
lean-ctx setup        # editor wiring, hooks, rules, this skill
lean-ctx doctor       # verify

Docs: https://leanctx.com/docs