/lean-ctx

name: lean-ctx
description: Use LeanCTX Context Gateway tools to select task-relevant code context, apply supported controls, reuse local knowledge and inspect recorded evidence. Use when lean-ctx MCP tools (ctx_*) are available or file, search or command output needs a focused view.

LeanCTX — Context Gateway for AI agents

Control what your AI can see. LeanCTX 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"|"callees", symbol=…)` | | 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"|"map")`; a range: `mode="lines:N-M"` | | 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"|"decision"|"task", value=…)`; durable project facts: `ctx_call(name="ctx_knowledge", arguments={"action": "remember", …})` |

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