yvgude/lean-ctx

GitHub: yvgude/lean-ctx

Stars: 2494 | Forks: 255

██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗ ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝ ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝ ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗ ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗ ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ **The Cognitive Context Layer for AI coding agents** Your AI coding agent wastes thousands of tokens rereading files, parsing noisy shell output, and losing context between sessions — and you have no control over any of it. **LeanCTX is the operating system for that context.** One local binary that governs every token between your code and the model: it **compresses** what the AI reads, **remembers** what matters across sessions, **routes** each read to the right fidelity, and **verifies** what comes back. Zero config required. Local-first. | Problem | With LeanCTX | |---------|-------------| | Repeated file reads: ~2000 tokens each | Cached re-reads: **~13 tokens** | | Raw `git status`: ~800 tokens | Compressed: **~120 tokens** | | Context resets every chat | Session memory persists across chats | | No visibility into context usage | Real-time dashboard + budget control |

Website · Docs · Install · Scenarios · Demo · Benchmarks · Cookbook · Security · Changelog

See it in action:

Map-mode file read + compressed git output demo

Read + Shell
Map-mode reads + compressed CLI output

Gain (live)
Tokens + USD savings in real time

Benchmark proof
Measure compression by language + mode

_{All GIFs are generated from reproducible VHS tapes in demo/.}

## Why developers use LeanCTX - **Longer useful coding sessions** — less context waste = more room for actual code reasoning - **Lower API costs** — 60-99% compression on shell output, cached reads cost ~13 tokens - **No more "I already showed you this file"** — session memory persists across chats - **Works with your existing setup** — one `lean-ctx setup` command, no config changes needed - **Full visibility** — see exactly where your context window budget goes

Saves you tokens? Give it a star — it helps others discover LeanCTX.

## What it does — the four dimensions of context LeanCTX treats context as a managed resource, not an afterthought. One binary covers the four dimensions that decide how well an AI agent actually performs: ### 1. Compression — input efficiency ### 2. Routing — the right fidelity per read Not every file needs the same depth. LeanCTX sends the signal, not the noise. - **10 read modes**: from full content down to AST signatures and entropy-filtered views - **Adaptive `ModePredictor`**: learns the optimal read mode per file type from past sessions - **`IntentEngine`**: classifies query complexity so simple lookups stay cheap ### 3. Memory — context that persists Context doesn't disappear between chats anymore. - **Session memory (CCP)**: persist task/facts/decisions across chats — structured recovery queries survive compaction - **Knowledge graph**: temporal facts with validity windows, episodic + procedural memory - **Property Graph**: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking ### 4. Verification — control what reaches the model Performance is accuracy, not just speed. You stay in control of the window. - **Context Manager**: browser dashboard with real-time token tracking, compression stats, utilization gauge - **Budgets & SLOs**: profiles, roles, per-agent budgets, and throttling policies - **Context Proof** (`ctx_proof`, `ctx_verify`): 4-layer verification engine with CI drift gates

Full feature list (67 MCP tools)

- **Graph-Powered Intelligence**: hybrid search (BM25 + embeddings + graph proximity via RRF), incremental git-diff updates - **LSP Refactoring** (`ctx_refactor`): language-server-powered rename, references, go-to-definition via rust-analyzer, typescript-language-server, pylsp, gopls - **Multi-Agent** (`ctx_agent`, `ctx_handoff`): agent handoff with context transfer bundles, diary system, synchronized shared state - **Archive Full-Text Search** (`ctx_expand search_all`): FTS5-powered cross-archive search over all previously archived tool outputs - **PR Context Packs**: `lean-ctx pack --pr` builds a PR-ready context pack (changed files, related tests, impact, artifacts) - **Context Packages**: `lean-ctx pack create` bundles Knowledge + Graph + Session into portable `.ctxpkg` files with SHA-256 integrity - **Observability**: `lean-ctx gain --live` for real-time savings, `lean-ctx wrapped` for weekly/monthly summaries (`gain --svg`/`--share` for a shareable card or self-hostable page), `lean-ctx watch` for TUI monitoring - **Verified savings**: `lean-ctx savings` is an auditable, per-event ledger (tokenizer transparency, bounce-netting, tamper-evident SHA-256 chain) — local-only, on by default - **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook + SDK)

## Where it's going LeanCTX is growing from a single context *layer* into a full **cognitive context layer** for whole teams: version-controlled context strategy, one unified graph, and a governance layer across many agents. - **Context as Code** — declarative pipelines, profiles, and policies in TOML, versioned like infrastructure - **Unified Context Graph** — code, tests, commits, CI runs, and knowledge entries in a single semantic graph - **Agent Harness** — roles, budgets, and tool permissions for multi-agent governance - **Context Observability** — SLOs on context consumption, anomaly detection, OpenTelemetry / Prometheus export The full roadmap lives in **[VISION.md](VISION.md)**. ## How it works (30 seconds) AI tool → (MCP tools + shell commands) → lean-ctx → your repo + CLI - **MCP server**: exposes `ctx_*` tools (read modes, caching, deltas, search, memory, multi-agent) - **Shell hook**: transparently compresses common commands so the LLM sees less noise - **Property Graph**: multi-edge code graph powers impact analysis, related file discovery, and search ranking - **Session memory**: persists state with structured recovery so long-running work never "cold starts" - **Context Manager**: browser dashboard for real-time visibility into what's in your context window ## Get started (60 seconds) # 1) Install (pick one) curl -fsSL https://leanctx.com/install.sh | sh # universal (no Rust needed) brew tap yvgude/lean-ctx && brew install lean-ctx # macOS / Linux npm install -g lean-ctx-bin # Node.js cargo install lean-ctx # Rust pi install npm:pi-lean-ctx # Pi Coding Agent # 2) Connect your AI tools (zero prompts, sensible defaults) lean-ctx onboard # or: lean-ctx setup (guided, full control) # 3) Verify lean-ctx doctor # 4) Restart your shell + AI tool, use it normally, then see the payoff lean-ctx gain # savings appear after your AI's first lean-ctx call After onboarding, restart your shell and your editor/AI tool once so the MCP + hooks are active. `lean-ctx gain` is empty until your AI tool makes its first lean-ctx call — that's expected, not a misconfiguration.

Troubleshooting / Safety

- Disable immediately (current shell): `lean-ctx-off` - Run a single command uncompressed: `lean-ctx -c --raw "git status"` - Only activate in AI agent sessions: set `shell_activation = "agents-only"` in `~/.config/lean-ctx/config.toml` - Per-project config override: create `.lean-ctx.toml` in your project root (auto-merged with global config) - Docker projects sharing `/workspace`: create `.lean-ctx-id` with a unique name to prevent context collisions - Update: `lean-ctx update` - Diagnose (shareable): `lean-ctx doctor --json`

## Real-world scenarios LeanCTX grows with you. Below are the journeys most people actually take — each links to a complete, function-by-function walkthrough in the **[Reference](docs/reference/README.md)** (every CLI command and all 63 MCP tools are documented there).

### 🟢 Your first 60 seconds "I just installed it — now what?" lean-ctx onboard # connect every detected AI tool lean-ctx doctor # confirm you're wired up One command auto-detects Cursor/Claude/Codex/… and configures MCP + hooks. → [Journey 1 — Setup & Onboarding](docs/reference/01-setup-and-onboarding.md)	### 📖 Coding every day "Stop re-reading the same files." lean-ctx read src/server.rs -m map # API surface, ~13 tok on re-read lean-ctx -c "git status" # compressed shell output
### 🧠 Resume where you left off "My new chat forgot everything." lean-ctx overview # task-aware project recap lean-ctx knowledge recall "auth" # facts that survive resets Session memory + a project knowledge graph persist across chats. → [Journey 3 — Memory & Knowledge](docs/reference/03-memory-and-knowledge.md)	### 🗺️ Understand a new codebase "Where does this function ripple to?" lean-ctx graph impact src/auth.rs # blast radius lean-ctx smells scan # code-smell hotspots A multi-edge property graph powers impact analysis + ranked search. → [Journey 4 — Code Intelligence](docs/reference/04-code-intelligence.md)
### 🔌 Wire in proxy, providers, plugins "Pull in GitHub issues and our Postgres schema." lean-ctx provider list lean-ctx serve --root ./api --root ./web # multi-repo External data flows through the same consolidation pipeline. → [Journey 5 — Advanced & Integrations](docs/reference/05-advanced.md)	### 🛠️ Keep it healthy "Update, fix, or cleanly remove." lean-ctx doctor --fix lean-ctx update Self-healing diagnostics; surgical uninstall that only removes its own blocks. → [Journey 6 — Lifecycle & Troubleshooting](docs/reference/06-lifecycle.md)
### 🎛️ Take control of the window "Budget my context like a pro." lean-ctx plan "refactor billing" --budget 8000 lean-ctx compile --mode balanced Phi-scored planning + knapsack compilation + a context ledger. → [Journey 7 — Context Engineering](docs/reference/07-context-engineering.md)	### 🤝 Run a team of agents "Planner + coder + reviewer on one repo." ctx_agent action=register role=dev ctx_handoff action=create # baton-pass with full context Shared message bus, diaries, knowledge, and deterministic handoffs. → [Journey 8 — Multi-Agent Collaboration](docs/reference/08-multi-agent.md)
### 🏢 Share across a team / CI "One shared index, headless in pipelines." lean-ctx team serve --config team.toml lean-ctx bootstrap # zero-prompt CI setup Scoped tokens, optional cloud sync, verifiable context gates. → [Journey 9 — Team, Cloud & CI](docs/reference/09-team-cloud-ci.md)	### 🎚️ Tune & govern "Make it behave exactly how we want." lean-ctx compression standard lean-ctx harden # enforce token discipline Compression levels, tool profiles, themes, and rules governance. → [Journey 10 — Customization & Governance](docs/reference/10-customization-and-governance.md)
### 📊 Prove the payoff "Show me the numbers." lean-ctx gain --deep # savings, cost, per-agent, heatmap lean-ctx wrapped # shareable recap (also: gain --svg / gain --share) lean-ctx savings # verified per-event ledger (auditable; savings verify) All analytics live in the CLI/dashboard — never burning agent tokens. → [Journey 11 — Analytics & Insights](docs/reference/11-analytics-and-insights.md)	### 📚 The full reference "I want to read everything." Every command and all 67 MCP tools, organized as user journeys, plus appendices for the [CLI map](docs/reference/appendix-cli-map.md), [MCP tools](docs/reference/appendix-mcp-tools.md), and [paths & config](docs/reference/appendix-paths-and-config.md). → [Reference index](docs/reference/README.md)

## Supported IDEs & AI tools LeanCTX is a standard **MCP server**, so it works with any MCP-compatible client. Two integration modes are auto-selected per agent: | Mode | How it works | Best for | |---|---|---| | **Hybrid** | MCP for cached reads (~13 tokens) + shell hooks for command compression | Agents with shell access (Cursor, Claude Code, Codex, ...) | | **MCP** | All 67 tools via MCP protocol, no shell hooks | Protocol-only agents (JetBrains, VS Code, Zed, ...) | ### Agent compatibility matrix | Agent | Hybrid | MCP | Setup | |---|:---:|:---:|---| | Cursor | ● | | `lean-ctx init --agent cursor` | | Claude Code | ● | | `lean-ctx init --agent claude` | | Augment CLI / VS Code | ● | | `lean-ctx init --agent augment` | | Codex CLI | ● | | `lean-ctx init --agent codex` | | Gemini CLI | ● | | `lean-ctx init --agent gemini` | | Windsurf | ● | | `lean-ctx init --agent windsurf` | | GitHub Copilot | ● | | `lean-ctx init --agent copilot` | | CRUSH | ● | | `lean-ctx init --agent crush` | | Hermes | ● | | `lean-ctx init --agent hermes` | | OpenCode | ● | | `lean-ctx init --agent opencode` | | Pi | ● | | `lean-ctx init --agent pi` | | Qoder | ● | | `lean-ctx init --agent qoder` | | Amp | ● | | `lean-ctx init --agent amp` | | Cline | ● | | `lean-ctx init --agent cline` | | Roo Code | ● | | `lean-ctx init --agent roo` | | Kiro | ● | | `lean-ctx init --agent kiro` | | Antigravity | ● | | `lean-ctx init --agent antigravity` | | Amazon Q | ● | | `lean-ctx init --agent amazonq` | | Qwen | ● | | `lean-ctx init --agent qwen` | | Trae | ● | | `lean-ctx init --agent trae` | | Verdent | ● | | `lean-ctx init --agent verdent` | | Aider | | ● | `lean-ctx init --agent aider` | | Continue | | ● | `lean-ctx init --agent continue` | | JetBrains IDEs | | ● | `lean-ctx init --agent jetbrains` | | QoderWork | | ● | `lean-ctx init --agent qoderwork` | | VS Code | | ● | `lean-ctx init --agent vscode` | | Zed | | ● | `lean-ctx init --agent zed` | | Neovim | | ● | `lean-ctx init --agent neovim` | | Emacs | | ● | `lean-ctx init --agent emacs` | | Sublime Text | | ● | `lean-ctx init --agent sublime` | ### When to use (and when not to) **Great fit if you...** - use AI coding tools daily and your sessions are shell-heavy (git/tests/builds) - work in medium/large repos (50+ files / monorepos) - want a local-first layer with **no telemetry by default** **Skip it if you...** - mostly work in tiny repos and rarely call the shell from your AI tool - always need raw/unfiltered logs (you can still use `--raw`, but ROI is lower) ## Demo Try these in any repo: lean-ctx read rust/src/server/mod.rs -m map lean-ctx -c "git log -n 5 --oneline" lean-ctx gain --live lean-ctx dashboard # Context Manager (browser) lean-ctx watch # TUI monitor lean-ctx benchmark report . - The repo ships the exact tapes used to render the GIFs in `demo/` - Regenerate locally: vhs demo/leanctx.tape vhs demo/gain.tape vhs demo/benchmark.tape ## Benchmarks - **Latest snapshot**: [BENCHMARKS.md](BENCHMARKS.md) - **Reproduce**: lean-ctx benchmark report . ## By the numbers - **1,800+ GitHub stars** in 4 months - **190+ forks** — active community contributions - **181 releases** — shipped daily since launch - **30+ supported AI coding agents** — broadest MCP compatibility - **67 MCP tools** — from simple file reads to multi-agent orchestration - Used in production by teams running Claude Code, Cursor, and Codex daily ## Docs - **Reference (every function, by user journey)**: [docs/reference/](docs/reference/README.md) — 11 journeys + CLI/MCP/config appendices - Getting started: https://leanctx.com/docs/getting-started - Tools reference: https://leanctx.com/docs/tools/ - CLI reference: https://leanctx.com/docs/cli-reference/ - Comparison (vs RTK, Context+, MemGPT): https://leanctx.com/compare/ - FAQ: [discord-faq.md](discord-faq.md) - Feature catalog (SSOT snapshot): [LEANCTX_FEATURE_CATALOG.md](LEANCTX_FEATURE_CATALOG.md) - Monorepo guide: [docs/guides/monorepo.md](docs/guides/monorepo.md) - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md) - Vision: [VISION.md](VISION.md) ## Privacy & security - **No telemetry by default** - **Optional anonymous stats sharing** (opt-in during setup) - **Disableable update check** (config `update_check_disabled = true` or `LEAN_CTX_NO_UPDATE_CHECK=1`) - **40+ security hardening fixes** in v3.5.16 (path traversal, injection, CSPRNG, CSP, resource limits — [details](CHANGELOG.md)) - Runs locally; your code never leaves your machine unless you explicitly enable cloud sync See [SECURITY.md](SECURITY.md). ## Uninstall One command removes **everything** — it stops all processes, then deletes hooks, editor configs, rules, autostart (LaunchAgent/systemd), the data dir, **and the binary itself**: lean-ctx uninstall # full clean removal lean-ctx uninstall --dry-run # preview every change, write nothing lean-ctx uninstall --keep-config # keep MCP configs + rules (for reinstall) lean-ctx-off # or just disable for the current shell session No binary on PATH (or you used the curl installer)? Run the same removal from the installer: curl -fsSL https://leanctx.com/install.sh | sh -s -- --uninstall If you installed via a package manager, `uninstall` removes everything it wrote and tells you the one command to finish removing the binary: brew uninstall lean-ctx # Homebrew cargo uninstall lean-ctx # cargo install npm uninstall -g lean-ctx-bin # npm pi uninstall npm:pi-lean-ctx # Pi Coding Agent ## License Apache License 2.0 — see [LICENSE](LICENSE).

标签：通知系统

### 🟢 Your first 60 seconds "I just installed it — now what?" lean-ctx onboard # connect every detected AI tool lean-ctx doctor # confirm you're wired up One command auto-detects Cursor/Claude/Codex/… and configures MCP + hooks. → [Journey 1 — Setup & Onboarding](docs/reference/01-setup-and-onboarding.md)	### 📖 Coding every day "Stop re-reading the same files." lean-ctx read src/server.rs -m map # API surface, ~13 tok on re-read lean-ctx -c "git status" # compressed shell output
### 🧠 Resume where you left off "My new chat forgot everything." lean-ctx overview # task-aware project recap lean-ctx knowledge recall "auth" # facts that survive resets Session memory + a project knowledge graph persist across chats. → [Journey 3 — Memory & Knowledge](docs/reference/03-memory-and-knowledge.md)	### 🗺️ Understand a new codebase "Where does this function ripple to?" lean-ctx graph impact src/auth.rs # blast radius lean-ctx smells scan # code-smell hotspots A multi-edge property graph powers impact analysis + ranked search. → [Journey 4 — Code Intelligence](docs/reference/04-code-intelligence.md)
### 🔌 Wire in proxy, providers, plugins "Pull in GitHub issues and our Postgres schema." lean-ctx provider list lean-ctx serve --root ./api --root ./web # multi-repo External data flows through the same consolidation pipeline. → [Journey 5 — Advanced & Integrations](docs/reference/05-advanced.md)	### 🛠️ Keep it healthy "Update, fix, or cleanly remove." lean-ctx doctor --fix lean-ctx update Self-healing diagnostics; surgical uninstall that only removes its own blocks. → [Journey 6 — Lifecycle & Troubleshooting](docs/reference/06-lifecycle.md)
### 🎛️ Take control of the window "Budget my context like a pro." lean-ctx plan "refactor billing" --budget 8000 lean-ctx compile --mode balanced Phi-scored planning + knapsack compilation + a context ledger. → [Journey 7 — Context Engineering](docs/reference/07-context-engineering.md)	### 🤝 Run a team of agents "Planner + coder + reviewer on one repo." ctx_agent action=register role=dev ctx_handoff action=create # baton-pass with full context Shared message bus, diaries, knowledge, and deterministic handoffs. → [Journey 8 — Multi-Agent Collaboration](docs/reference/08-multi-agent.md)
### 🏢 Share across a team / CI "One shared index, headless in pipelines." lean-ctx team serve --config team.toml lean-ctx bootstrap # zero-prompt CI setup Scoped tokens, optional cloud sync, verifiable context gates. → [Journey 9 — Team, Cloud & CI](docs/reference/09-team-cloud-ci.md)	### 🎚️ Tune & govern "Make it behave exactly how we want." lean-ctx compression standard lean-ctx harden # enforce token discipline Compression levels, tool profiles, themes, and rules governance. → [Journey 10 — Customization & Governance](docs/reference/10-customization-and-governance.md)
### 📊 Prove the payoff "Show me the numbers." lean-ctx gain --deep # savings, cost, per-agent, heatmap lean-ctx wrapped # shareable recap (also: gain --svg / gain --share) lean-ctx savings # verified per-event ledger (auditable; savings verify) All analytics live in the CLI/dashboard — never burning agent tokens. → [Journey 11 — Analytics & Insights](docs/reference/11-analytics-and-insights.md)	### 📚 The full reference "I want to read everything." Every command and all 67 MCP tools, organized as user journeys, plus appendices for the [CLI map](docs/reference/appendix-cli-map.md), [MCP tools](docs/reference/appendix-mcp-tools.md), and [paths & config](docs/reference/appendix-paths-and-config.md). → [Reference index](docs/reference/README.md)