wehub-resource-sync
26382a7ac6
8.4 KiB
lean-ctx Reference — Every Function, Every Path
This is the complete, function-by-function reference for lean-ctx, organized the way you actually meet it: as a sequence of user journeys, starting at setup and walking through everything lean-ctx can do.
Each journey document answers three questions for every feature:
- What does it do? (plain language)
- How do I use it? (the exact command / MCP call)
- What happens under the hood? (which code path runs, what files change)
New to lean-ctx? Read the journeys in order. Looking for one command? Use the index below.
The journeys
| # | Journey | You are… | Covers |
|---|---|---|---|
| 1 | Setup & Onboarding | installing for the first time | onboard, setup, install, bootstrap, init, doctor, status |
| 2 | Daily Use | coding with your AI every day | read, grep, find, ls, -c/exec, gain, tools |
| 3 | Memory & Knowledge | wanting continuity across sessions | session, sessions, knowledge, overview, CCP |
| 4 | Code Intelligence | exploring or refactoring a codebase | graph, impact, repomap, smells, visualize, index |
| 5 | Advanced & Integrations | wiring up proxy, providers, plugins | proxy, provider, serve, plugin, rules, pack, multi-repo |
| 6 | Lifecycle & Troubleshooting | updating, fixing, or removing | update, uninstall, stop, restart, cache, doctor --fix |
| 7 | Context Engineering & Observability | actively managing the context window | radar, control, plan, compile, ledger, preload, compose, verify |
| 8 | Multi-Agent Collaboration | running several agents on one project | ctx_agent, ctx_task, ctx_handoff, ctx_share, diaries, shared knowledge |
| 9 | Team, Cloud & CI | sharing across a team or running headless | team serve/token/sync, login, sync, contribute, bootstrap, serve |
| 10 | Customization & Governance | tuning behavior & enforcing rules | compression, tools, profile, config, theme, filter, rules, harden |
| 11 | Analytics, Insights & Reporting | measuring savings & finding waste | gain, wrapped, token-report, discover, ghost, dashboard, watch, cep, stats |
| 12 | Troubleshooting Playbook | something's not working | symptom → diagnosis → fix; status, doctor, doctor integrations, sessions doctor, report-issue |
| 13 | Security & Governance | putting lean-ctx in front of real code | PathJail, shell_allowlist, secret_detection, sandbox, harden, role policies |
| 14 | Performance Tuning | huge repo / constrained machine | memory_profile, bm25_max_cache_mb, graph_index_max_files, LEAN_CTX_MAX_*, slow-log |
| 18 | Adaptive Learning | understanding how lean-ctx tunes itself | learned thresholds, LITM calibration, scent field, playbook, learning export/import, efficacy |
| 19 | JetBrains-Plugin | using code intelligence from a running JetBrains IDE | ctx_refactor: navigation, structure, inspections, symbol-edits, rename/reformat/move/safe_delete/inline |
| 20 | Hermes Context Engine | embedding lean-ctx as your agent's context engine | ctx_transcript_compact, serve, context.engine, recall tools, session lifecycle |
| 22 | Code Health | paying to re-read tangled, complex code | ctx_quality, lean-ctx health [--gate], cognitive complexity (S3776), navigability, edit-gate, gain navigability |
Cross-cutting references
| Reference | What's in it |
|---|---|
| Per-IDE quickstarts | Copy-paste setup + verify for Cursor, Claude, Codex, VS Code, JetBrains |
| CLI command map | Every CLI command + alias, one line each |
| MCP tool map | Every MCP tool, params, and which profile exposes it |
| Paths, env vars & config | Data dir layout, every LEAN_CTX_* var, every config key |
| Glossary | MCP, CCP, hooks, modes, profiles, proxy — in one place |
| JetBrains-Plugin | Compact agent lookup for the JetBrains plugin — every ctx_refactor action, endpoint, guard, error. Full guide: Journey 19 |
Generated, always-current appendices (rendered directly from the code, so they can never drift): MCP tools (every registered tool + parameters) and config keys (every
config.tomlkey with type, default, and env override). Regenerate withcargo run --example gen_docs --features dev-tools; CI fails if they are stale.
The two mental models you need
lean-ctx has exactly two ways of helping your AI, and almost every command belongs to one of them:
- MCP tools — your AI editor calls
ctx_*tools instead of its native file reads/search. lean-ctx returns compressed, cached results. (Journeys 2–5.) - Shell hooks — when you (or your AI's terminal) run
git,npm,cargo, etc., lean-ctx compresses the output. (Journey 2.)
Everything else — sessions, knowledge, graph, proxy — exists to make those two paths smarter. If you remember only that, the rest falls into place.
The journeys layer onto this: 1–4 are the core daily loop, 5 wires in external systems, 6 keeps it healthy, 7 gives you fine-grained control of the window, 8–9 scale it to multiple agents and teams, and 10–11 let you tune behavior and measure the payoff. 12–14 are the operations track: a central troubleshooting playbook, the security/governance surface, and performance tuning for big repos and constrained machines. Every CLI command and MCP tool appears in at least one journey and in the appendices below.