LeanCTX (lean-ctx) — Context Gateway for AI agents.
lean-ctx routing — the host's built-in tools map to:
• Read/cat -> ctx_read(path, mode)
• Grep -> ctx_search(pattern, path)
• Shell/bash -> ctx_shell(command)
• Glob/find -> ctx_glob(pattern)
• ls/find -> ctx_tree(path, depth)
This covers built-in file/search/shell tools only; other MCP servers keep their own jobs.
Call the tool; describing a call does not run it.
By task:
• Unfamiliar code -> ctx_compose (search + read + symbols in one call)
• Read -> ctx_read(mode=signatures|map|full); edit -> ctx_patch
• Symbol -> ctx_search(action=symbol); meaning -> ctx_search(action=semantic)
• Callers/impact -> ctx_callgraph; memory -> ctx_session / ctx_knowledge
AGENT LOOP (phase -> tool):
• Orient — understand before acting -> ctx_compose
• Find — exact symbol by name -> ctx_search(action=symbol)
• Read — a file, structurally -> ctx_read(mode=signatures|map)
• Locate — a pattern across files -> ctx_search
• Trace — callers / callees / blast radius -> ctx_callgraph
• Verify — after an edit -> ctx_shell(test/build) + native lints
Anti-patterns — do NOT:
• Chain ctx_search -> ctx_read -> ctx_search(action=symbol) — one ctx_compose replaces all three
• Use ctx_read(mode=full) for orientation — use mode=signatures
• Use ctx_callgraph/ctx_graph for const/static/variable refs — they track call edges and file deps only; use ctx_search instead
NAVIGATION PARADOX: reading more ≠ understanding more.
• Semantic question ("where/how is X handled?") -> ctx_search (BM25) + ctx_search(action=semantic) (meaning), not whole-file reads
• Hidden architectural deps (who calls this, what breaks) -> ctx_callgraph / ctx_graph — for these only
• Navigate structure (signatures, symbols) before reading entire files
PARALLEL: fire independent tool calls in the SAME turn — ctx_compose bundles multiple lookups into one call.
Long shell jobs: ctx_shell(run_in_background=true), then poll job_id. ctx_session=memory; full guide: LEAN-CTX.md
RECOVER: compressed output is reversible — never re-read line-by-line. Need full/exact? Read the shown file path with any tool (no MCP), or ctx_read(mode=full|raw=true); [Archived]/tee/firewall → ctx_expand(id=...).
ROOTS: ctx_* read ~ projects, write the active one; ~/.ssh etc. closed. Use native Read for out-of-root; `lean-ctx doctor` shows effective roots.
CEP v1: 1.ACT FIRST 2.DELTA ONLY (Fn refs) 3.STRUCTURED (+/-/~) 4.ONE LINE PER ACTION 5.QUALITY ANCHOR
SOLUTION EFFICIENCY: stop at first level that applies:
skip (YAGNI) → reuse codebase → stdlib → native platform → installed dep → one-line → minimum code.
Never skip: validation, security, error handling.