{"id":47676801,"url":"https://github.com/yvgude/lean-ctx","last_synced_at":"2026-06-16T01:01:52.652Z","repository":{"id":346423246,"uuid":"1189918673","full_name":"yvgude/lean-ctx","owner":"yvgude","description":"The Context OS for AI Development. Reduce token waste in Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini \u0026 more by 60–95% (up to 99% on cached reads) Shell Hook + MCP Server · 49 tools · 10 read modes · 90+ patterns · Single Rust binary ","archived":false,"fork":false,"pushed_at":"2026-05-05T19:45:11.000Z","size":426499,"stargazers_count":1087,"open_issues_count":1,"forks_count":118,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-05-05T21:28:57.443Z","etag":null,"topics":["agentic-coding","ai","ai-coding","claude-code","context-engineering","copilot","cursor","developer-tools","gemini-cli","llm","mcp","mcp-server","reduce-token-costs","rust","token-optimization"],"latest_commit_sha":null,"homepage":"https://leanctx.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yvgude.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-23T19:48:59.000Z","updated_at":"2026-05-05T20:55:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yvgude/lean-ctx","commit_stats":null,"previous_names":["yvgude/lean-ctx"],"tags_count":153,"template":false,"template_full_name":null,"purl":"pkg:github/yvgude/lean-ctx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvgude%2Flean-ctx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvgude%2Flean-ctx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvgude%2Flean-ctx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvgude%2Flean-ctx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yvgude","download_url":"https://codeload.github.com/yvgude/lean-ctx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yvgude%2Flean-ctx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32825593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai","ai-coding","claude-code","context-engineering","copilot","cursor","developer-tools","gemini-cli","llm","mcp","mcp-server","reduce-token-costs","rust","token-optimization"],"created_at":"2026-04-02T13:33:35.284Z","updated_at":"2026-06-16T01:01:52.635Z","avatar_url":"https://github.com/yvgude.png","language":"Rust","funding_links":[],"categories":["MCP 服务器精选列表","CLIs","Skills","技能列表","Optimizations","AI","Development tools","Rust","Agent Infrastructure","Development Tools"],"sub_categories":["💻 开发与代码执行","Usage","Development \u0026 Code Tools","开发与代码工具","Profiling","Agents","Workflow Automation","Configuration \u0026 Context Management"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpre\u003e\n██╗     ███████╗ █████╗ ███╗   ██╗     ██████╗████████╗██╗  ██╗\n██║     ██╔════╝██╔══██╗████╗  ██║    ██╔════╝╚══██╔══╝╚██╗██╔╝\n██║     █████╗  ███████║██╔██╗ ██║    ██║        ██║    ╚███╔╝ \n██║     ██╔══╝  ██╔══██║██║╚██╗██║    ██║        ██║    ██╔██╗ \n███████╗███████╗██║  ██║██║ ╚████║    ╚██████╗   ██║   ██╔╝ ██╗\n╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝     ╚═════╝   ╚═╝   ╚═╝  ╚═╝\n\u003c/pre\u003e\n\n### **Control what your AI can see.**\n\n**LeanCTX — Lean Context Intelligence for AI agents**\n\nLeanCTX — short for **Lean Context** — is the context intelligence layer for\nAI agents. It runs as a single local binary between your agents and your code,\nshell and data: it **decides** what they read, **remembers** what they learn,\n**guards** what they touch — and **proves** what they save with a signed,\nverifiable savings ledger. The result: 60–90% fewer tokens — and that's the\nreceipt, not the product. Zero config required. Local-first.\n\n| Problem | With LeanCTX |\n|---------|-------------|\n| Repeated file reads: ~2000 tokens each | Cached re-reads: **~13 tokens** |\n| Raw `git status`: ~800 tokens | Compressed: **~120 tokens** |\n| Context resets every chat | Session memory persists across chats |\n| No visibility into context usage | Real-time dashboard + budget control |\n\n---\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/yvgude/lean-ctx/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/yvgude/lean-ctx?style=social\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml\"\u003e\u003cimg src=\"https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml/badge.svg\" alt=\"Security\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/lean-ctx\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/lean-ctx?color=%23e6522c\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/lean-ctx\"\u003e\u003cimg src=\"https://img.shields.io/crates/d/lean-ctx?color=%23e6522c\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/lean-ctx-bin\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/lean-ctx-bin?label=npm\u0026color=%23cb3837\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://aur.archlinux.org/packages/lean-ctx\"\u003e\u003cimg src=\"https://img.shields.io/aur/version/lean-ctx?color=%231793d1\" alt=\"AUR\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pi.dev/packages/pi-lean-ctx\"\u003e\u003cimg src=\"https://img.shields.io/badge/Pi.dev-pi--lean--ctx-6366f1?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHRleHQgeD0iNCIgeT0iMTgiIGZvbnQtc2l6ZT0iMTYiIGZvbnQtZmFtaWx5PSJzZXJpZiI+z4A8L3RleHQ+PC9zdmc+\" alt=\"Pi.dev\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/pTHkG9Hew9\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-Join-5865F2?logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/leanctx\"\u003e\u003cimg src=\"https://img.shields.io/badge/𝕏-Follow-000000?logo=x\u0026logoColor=white\" alt=\"X/Twitter\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Telemetry-Opt--in%20Only-brightgreen?logo=shield\u0026logoColor=white\" alt=\"Opt-in Telemetry\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://leanctx.com\"\u003eWebsite\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"https://leanctx.com/docs/getting-started\"\u003eDocs\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"#get-started-60-seconds\"\u003eInstall\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"#real-world-scenarios\"\u003eScenarios\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"#demo\"\u003eDemo\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"#benchmarks\"\u003eBenchmarks\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"cookbook/README.md\"\u003eCookbook\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"SECURITY.md\"\u003eSecurity\u003c/a\u003e\u0026nbsp;\u0026nbsp;·\u0026nbsp;\u0026nbsp;\u003ca href=\"CHANGELOG.md\"\u003eChangelog\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003e **Control what your AI can see.** LeanCTX — short for **Lean Context** — is the **context intelligence layer** for AI agents: one local Rust binary that decides what your agents read, remembers what they learn, guards what they touch — and proves what they save.\n\n\u003e Token savings are the receipt. Intelligence is the product. Works with **Cursor, Claude Code, Copilot, Windsurf, Codex, Gemini** and 30+ other agents — no config needed.\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eSee it in action:\u003c/strong\u003e\u003c/p\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003cimg src=\"assets/leanctx-demo.gif\" width=\"320\" alt=\"Map-mode file read + compressed git output demo\"\u003e\n      \u003cbr/\u003e\n      \u003cstrong\u003eRead + Shell\u003c/strong\u003e\n      \u003cbr/\u003e\n      Map-mode reads + compressed CLI output\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003cimg src=\"assets/leanctx-gain.gif\" width=\"320\" alt=\"lean-ctx gain live dashboard demo\"\u003e\n      \u003cbr/\u003e\n      \u003cstrong\u003eGain (live)\u003c/strong\u003e\n      \u003cbr/\u003e\n      Tokens + USD savings in real time\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"33%\"\u003e\n      \u003cimg src=\"assets/leanctx-benchmark.gif\" width=\"320\" alt=\"lean-ctx benchmark report demo\"\u003e\n      \u003cbr/\u003e\n      \u003cstrong\u003eBenchmark proof\u003c/strong\u003e\n      \u003cbr/\u003e\n      Measure compression by language + mode\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eAll GIFs are generated from reproducible VHS tapes in \u003ccode\u003edemo/\u003c/code\u003e.\u003c/sub\u003e\u003c/p\u003e\n\n## Why developers use LeanCTX\n\n- **Longer useful coding sessions** — less context waste = more room for actual code reasoning\n- **Lower API costs** — 60–90% fewer tokens on reads and shell output, cached re-reads cost ~13 tokens\n- **No more \"I already showed you this file\"** — session memory persists across chats\n- **Works with your existing setup** — one `lean-ctx setup` command, no config changes needed\n- **Full visibility** — see exactly where your context window budget goes\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eSaves you tokens?\u003c/strong\u003e \u003ca href=\"https://github.com/yvgude/lean-ctx\"\u003eGive it a star\u003c/a\u003e — it helps others discover LeanCTX.\n\u003c/p\u003e\n\n---\n\n## What it does — the four dimensions of context\n\nLeanCTX treats context as a managed resource, not an afterthought. One binary\ncovers the four dimensions that decide how well an AI agent actually performs:\n\n### 1. Compression — input efficiency\n\nYour AI agent reads files and runs commands. LeanCTX compresses both automatically.\n\n- **File reads**: 10 read modes (`full`, `map`, `signatures`, `diff`, `lines:N-M`, `density:X`, …) — cached re-reads cost ~13 tokens\n- **Target density** (`density:0.4`): SDE-style budget compression — keeps the highest-entropy lines until ~40% of the original tokens remain, deterministic\n- **JIT disclosure**: `signatures` carries line spans and points at `lines:N-M` for targeted expansion — outline first, bodies on demand\n- **Shell output**: 95+ shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and more (270 passthrough rules)\n- **Tree-sitter AST**: structural understanding for 18 languages — not just text compression\n\n### 2. Routing — the right fidelity per read\n\nNot every file needs the same depth. LeanCTX sends the signal, not the noise.\n\n- **10 read modes**: from full content down to AST signatures and entropy-filtered views\n- **Adaptive `ModePredictor`**: learns the optimal read mode per file type from past sessions\n- **`IntentEngine`**: classifies query complexity so simple lookups stay cheap\n\n### 3. Memory — context that persists\n\nContext doesn't disappear between chats anymore.\n\n- **Session memory (CCP)**: persist task/facts/decisions across chats — structured recovery queries survive compaction\n- **Knowledge graph**: temporal facts with validity windows, episodic + procedural memory\n- **Property Graph**: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking\n\n### 4. Verification — control what reaches the model\n\nPerformance is accuracy, not just speed. You stay in control of the window.\n\n- **Context Manager**: browser dashboard with real-time token tracking, compression stats, utilization gauge\n- **Budgets \u0026 SLOs**: profiles, roles, per-agent budgets, and throttling policies\n- **Context Proof** (`ctx_proof`, `ctx_verify`): 4-layer verification engine with CI drift gates\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull feature list (76 MCP tools)\u003c/strong\u003e\u003c/summary\u003e\n\n- **Web \u0026 Research** (`ctx_url_read`): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — `facts`/`quotes` return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only)\n- **Graph-Powered Intelligence**: hybrid search (BM25 + embeddings + graph proximity via RRF), incremental git-diff updates\n- **LSP Refactoring** (`ctx_refactor`): language-server-powered rename, references, go-to-definition via rust-analyzer, typescript-language-server, pylsp, gopls\n- **Multi-Agent** (`ctx_agent`, `ctx_handoff`): agent handoff with context transfer bundles, diary system, synchronized shared state\n- **Archive Full-Text Search** (`ctx_expand search_all`): FTS5-powered cross-archive search over all previously archived tool outputs\n- **PR Context Packs**: `lean-ctx pack --pr` builds a PR-ready context pack (changed files, related tests, impact, artifacts)\n- **Context Packages**: `lean-ctx pack create` bundles Knowledge + Graph + Session into portable `.ctxpkg` files with SHA-256 integrity\n- **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\n- **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\n- **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook + SDK)\n\n\u003c/details\u003e\n\n## Where it's going\n\nLeanCTX is growing from a single context *layer* into a full **cognitive context\nlayer** for whole teams: version-controlled context strategy, one unified graph, and a\ngovernance layer across many agents.\n\n- **Context as Code** — declarative pipelines, profiles, and policies in TOML, versioned like infrastructure\n- **Unified Context Graph** — code, tests, commits, CI runs, and knowledge entries in a single semantic graph\n- **Agent Harness** — roles, budgets, and tool permissions for multi-agent governance\n- **Context Observability** — SLOs on context consumption, anomaly detection, OpenTelemetry / Prometheus export\n\nThe full roadmap lives in **[VISION.md](VISION.md)**.\n\n## How it works (30 seconds)\n\n```\nAI tool  →  (MCP tools + shell commands)  →  lean-ctx  →  your repo + CLI\n```\n\n- **MCP server**: exposes `ctx_*` tools (read modes, caching, deltas, search, memory, multi-agent)\n- **Shell hook**: transparently compresses common commands so the LLM sees less noise\n- **Property Graph**: multi-edge code graph powers impact analysis, related file discovery, and search ranking\n- **Session memory**: persists state with structured recovery so long-running work never \"cold starts\"\n- **Context Manager**: browser dashboard for real-time visibility into what's in your context window\n\n## Get started (60 seconds)\n\n```bash\n# 1) Install (pick one)\ncurl -fsSL https://leanctx.com/install.sh | sh      # universal (no Rust needed)\nbrew tap yvgude/lean-ctx \u0026\u0026 brew install lean-ctx    # macOS / Linux\nnpm install -g lean-ctx-bin                          # Node.js\ncargo install lean-ctx                               # Rust\npi install npm:pi-lean-ctx                           # Pi Coding Agent\n\n# 2) Connect your AI tools (zero prompts, sensible defaults)\nlean-ctx onboard          # or: lean-ctx setup  (guided, full control)\n\n# 3) Verify\nlean-ctx doctor\n\n# 4) Restart your shell + AI tool, use it normally, then see the payoff\nlean-ctx gain             # savings appear after your AI's first lean-ctx call\n```\n\nAfter 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting / Safety\u003c/strong\u003e\u003c/summary\u003e\n\n- Disable immediately (current shell): `lean-ctx-off`\n- Run a single command uncompressed: `lean-ctx -c --raw \"git status\"`\n- Only activate in AI agent sessions: set `shell_activation = \"agents-only\"` in `~/.config/lean-ctx/config.toml`\n- Per-project config override: create `.lean-ctx.toml` in your project root (auto-merged with global config)\n- Docker projects sharing `/workspace`: create `.lean-ctx-id` with a unique name to prevent context collisions\n- Update: `lean-ctx update`\n- Diagnose (shareable): `lean-ctx doctor --json`\n\n\u003c/details\u003e\n\n## Real-world scenarios\n\nLeanCTX grows with you. Below are the journeys most people actually take — each\nlinks to a complete, function-by-function walkthrough in the\n**[Reference](docs/reference/README.md)** (every CLI command and all 76 MCP\ntools are documented there).\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🟢 Your first 60 seconds\n*\"I just installed it — now what?\"*\n\n```bash\nlean-ctx onboard      # connect every detected AI tool\nlean-ctx doctor       # confirm you're wired up\n```\nOne command auto-detects Cursor/Claude/Codex/… and configures MCP + hooks.\n→ **[Journey 1 — Setup \u0026 Onboarding](docs/reference/01-setup-and-onboarding.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 📖 Coding every day\n*\"Stop re-reading the same files.\"*\n\n```bash\nlean-ctx read src/server.rs -m map   # API surface, ~13 tok on re-read\nlean-ctx -c \"git status\"             # compressed shell output\n```\nYour agent reads less and searches smarter — automatically.\n→ **[Journey 2 — Daily Use](docs/reference/02-daily-use.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🧠 Resume where you left off\n*\"My new chat forgot everything.\"*\n\n```bash\nlean-ctx overview                    # task-aware project recap\nlean-ctx knowledge recall \"auth\"     # facts that survive resets\n```\nSession memory + a project knowledge graph persist across chats.\n→ **[Journey 3 — Memory \u0026 Knowledge](docs/reference/03-memory-and-knowledge.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🗺️ Understand a new codebase\n*\"Where does this function ripple to?\"*\n\n```bash\nlean-ctx graph impact src/auth.rs    # blast radius\nlean-ctx smells scan                 # code-smell hotspots\n```\nA multi-edge property graph powers impact analysis + ranked search.\n→ **[Journey 4 — Code Intelligence](docs/reference/04-code-intelligence.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🔌 Wire in proxy, providers, plugins\n*\"Pull in GitHub issues and our Postgres schema.\"*\n\n```bash\nlean-ctx provider list\nlean-ctx serve --root ./api --root ./web   # multi-repo\n```\nExternal data flows through the same consolidation pipeline.\n→ **[Journey 5 — Advanced \u0026 Integrations](docs/reference/05-advanced.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🛠️ Keep it healthy\n*\"Update, fix, or cleanly remove.\"*\n\n```bash\nlean-ctx doctor --fix\nlean-ctx update\n```\nSelf-healing diagnostics; surgical uninstall that only removes its own blocks.\n→ **[Journey 6 — Lifecycle \u0026 Troubleshooting](docs/reference/06-lifecycle.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🎛️ Take control of the window\n*\"Budget my context like a pro.\"*\n\n```bash\nlean-ctx plan \"refactor billing\" --budget 8000\nlean-ctx compile --mode balanced\n```\nPhi-scored planning + knapsack compilation + a context ledger.\n→ **[Journey 7 — Context Engineering](docs/reference/07-context-engineering.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🤝 Run a team of agents\n*\"Planner + coder + reviewer on one repo.\"*\n\n```text\nctx_agent action=register role=dev\nctx_handoff action=create        # baton-pass with full context\n```\nShared message bus, diaries, knowledge, and deterministic handoffs.\n→ **[Journey 8 — Multi-Agent Collaboration](docs/reference/08-multi-agent.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🏢 Share across a team / CI\n*\"One shared index, headless in pipelines.\"*\n\n```bash\nlean-ctx team serve --config team.toml\nlean-ctx bootstrap            # zero-prompt CI setup\n```\nScoped tokens, optional cloud sync, verifiable context gates.\n→ **[Journey 9 — Team, Cloud \u0026 CI](docs/reference/09-team-cloud-ci.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 🎚️ Tune \u0026 govern\n*\"Make it behave exactly how we want.\"*\n\n```bash\nlean-ctx compression standard\nlean-ctx harden               # enforce token discipline\n```\nCompression levels, tool profiles, themes, and rules governance.\n→ **[Journey 10 — Customization \u0026 Governance](docs/reference/10-customization-and-governance.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 📊 Prove the payoff\n*\"Show me the numbers.\"*\n\n```bash\nlean-ctx gain --deep          # savings, cost, per-agent, heatmap\nlean-ctx wrapped              # shareable recap (also: gain --svg / gain --share)\nlean-ctx savings              # verified per-event ledger (auditable; savings verify)\n```\nAll analytics live in the CLI/dashboard — never burning agent tokens.\n→ **[Journey 11 — Analytics \u0026 Insights](docs/reference/11-analytics-and-insights.md)**\n\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\n### 📚 The full reference\n*\"I want to read everything.\"*\n\nEvery command and all 76 MCP tools, organized as user journeys, plus\nappendices for the [CLI map](docs/reference/appendix-cli-map.md),\n[MCP tools](docs/reference/appendix-mcp-tools.md), and\n[paths \u0026 config](docs/reference/appendix-paths-and-config.md).\n→ **[Reference index](docs/reference/README.md)**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Supported IDEs \u0026 AI tools\n\nLeanCTX is a standard **MCP server**, so it works with any MCP-compatible client. Two integration modes are auto-selected per agent:\n\n| Mode | How it works | Best for |\n|---|---|---|\n| **Hybrid** | MCP for cached reads (~13 tokens) + shell hooks for command compression | Agents with shell access (Cursor, Claude Code, Codex, ...) |\n| **MCP** | All 76 tools via MCP protocol, no shell hooks | Protocol-only agents (JetBrains, VS Code, Zed, ...) |\n\n### Agent compatibility matrix\n\n| Agent | Hybrid | MCP | Setup |\n|---|:---:|:---:|---|\n| Cursor | ● | | `lean-ctx init --agent cursor` |\n| Claude Code | ● | | `lean-ctx init --agent claude` |\n| CodeBuddy | ● | | `lean-ctx init --agent codebuddy` |\n| Augment CLI / VS Code | ● | | `lean-ctx init --agent augment` |\n| Codex CLI | ● | | `lean-ctx init --agent codex` |\n| Gemini CLI | ● | | `lean-ctx init --agent gemini` |\n| Windsurf | ● | | `lean-ctx init --agent windsurf` |\n| GitHub Copilot | ● | | `lean-ctx init --agent copilot` |\n| CRUSH | ● | | `lean-ctx init --agent crush` |\n| Hermes | ● | | `lean-ctx init --agent hermes` |\n| OpenCode | ● | | `lean-ctx init --agent opencode` |\n| Pi | ● | | `lean-ctx init --agent pi` |\n| Qoder | ● | | `lean-ctx init --agent qoder` |\n| Amp | ● | | `lean-ctx init --agent amp` |\n| Cline | ● | | `lean-ctx init --agent cline` |\n| Roo Code | ● | | `lean-ctx init --agent roo` |\n| Kiro | ● | | `lean-ctx init --agent kiro` |\n| Antigravity | ● | | `lean-ctx init --agent antigravity` |\n| Amazon Q | ● | | `lean-ctx init --agent amazonq` |\n| Qwen | ● | | `lean-ctx init --agent qwen` |\n| Trae | ● | | `lean-ctx init --agent trae` |\n| Verdent | ● | | `lean-ctx init --agent verdent` |\n| Aider | | ● | `lean-ctx init --agent aider` |\n| Continue | | ● | `lean-ctx init --agent continue` |\n| JetBrains IDEs | | ● | `lean-ctx init --agent jetbrains` |\n| QoderWork | | ● | `lean-ctx init --agent qoderwork` |\n| VS Code | | ● | `lean-ctx init --agent vscode` |\n| Zed | | ● | `lean-ctx init --agent zed` |\n| Neovim | | ● | `lean-ctx init --agent neovim` |\n| Emacs | | ● | `lean-ctx init --agent emacs` |\n| Sublime Text | | ● | `lean-ctx init --agent sublime` |\n\n\u003e **Any MCP-compatible client** works out of the box — the table above shows agents with first-class auto-setup.\n\n### When to use (and when not to)\n\n**Great fit if you...**\n- use AI coding tools daily and your sessions are shell-heavy (git/tests/builds)\n- work in medium/large repos (50+ files / monorepos)\n- want a local-first layer with **no telemetry by default**\n\n**Skip it if you...**\n- mostly work in tiny repos and rarely call the shell from your AI tool\n- always need raw/unfiltered logs (you can still use `--raw`, but ROI is lower)\n\n\u003ca id=\"demo\"\u003e\u003c/a\u003e\n\n## Demo\n\nTry these in any repo:\n\n```bash\nlean-ctx read rust/src/server/mod.rs -m map\nlean-ctx -c \"git log -n 5 --oneline\"\nlean-ctx gain --live\nlean-ctx dashboard                              # Context Manager (browser)\nlean-ctx watch                                  # TUI monitor\nlean-ctx benchmark report .\n```\n\n- The repo ships the exact tapes used to render the GIFs in `demo/`\n- Regenerate locally:\n\n```bash\nvhs demo/leanctx.tape\nvhs demo/gain.tape\nvhs demo/benchmark.tape\n```\n\n\u003ca id=\"benchmarks\"\u003e\u003c/a\u003e\n\n## Benchmarks\n\n- **Latest snapshot**: [BENCHMARKS.md](BENCHMARKS.md)\n- **Reproduce**:\n\n```bash\nlean-ctx benchmark report .\n```\n\n## By the numbers\n\n- **2,600+ GitHub stars** — and counting\n- **260+ forks** — active community contributions\n- **200+ releases** — shipped near-daily since launch\n- **30+ supported AI coding agents** — broadest MCP compatibility\n- **76 MCP tools** — from simple file reads to multi-agent orchestration\n- Used in production by teams running Claude Code, Cursor, and Codex daily\n- **Live adoption metrics**: [leanctx.com/metrics](https://leanctx.com/metrics/) — installs, stars and savings, updated continuously\n\n## Docs\n\n- **Reference (every function, by user journey)**: [docs/reference/](docs/reference/README.md) — 11 journeys + CLI/MCP/config appendices\n- Getting started: https://leanctx.com/docs/getting-started\n- Tools reference: https://leanctx.com/docs/tools/\n- CLI reference: https://leanctx.com/docs/cli-reference/\n- What is LeanCTX: https://leanctx.com/what-is-leanctx/\n- Comparison (vs RTK, Context+, MemGPT): https://leanctx.com/compare/\n- Pricing \u0026 Cloud (local use is free forever): https://leanctx.com/pricing/\n- FAQ: [discord-faq.md](discord-faq.md)\n- Feature catalog (SSOT snapshot): [LEANCTX_FEATURE_CATALOG.md](LEANCTX_FEATURE_CATALOG.md)\n- Monorepo guide: [docs/guides/monorepo.md](docs/guides/monorepo.md)\n- Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)\n- Vision: [VISION.md](VISION.md)\n\n## Privacy \u0026 security\n\n- **No telemetry by default**\n- **Optional anonymous stats sharing** (opt-in during setup)\n- **Disableable update check** (config `update_check_disabled = true` or `LEAN_CTX_NO_UPDATE_CHECK=1`)\n- **40+ security hardening fixes** in v3.5.16 (path traversal, injection, CSPRNG, CSP, resource limits — [details](CHANGELOG.md))\n- Runs locally; your code never leaves your machine unless you explicitly enable cloud sync\n\nSee [SECURITY.md](SECURITY.md).\n\n## Uninstall\n\nOne command removes **everything** — it stops all processes, then deletes hooks,\neditor configs, rules, autostart (LaunchAgent/systemd), the data dir, **and the\nbinary itself**:\n\n```bash\nlean-ctx uninstall                 # full clean removal\nlean-ctx uninstall --dry-run       # preview every change, write nothing\nlean-ctx uninstall --keep-config   # keep MCP configs + rules (for reinstall)\nlean-ctx-off                       # or just disable for the current shell session\n```\n\nNo binary on PATH (or you used the curl installer)? Run the same removal from the installer:\n\n```bash\ncurl -fsSL https://leanctx.com/install.sh | sh -s -- --uninstall\n```\n\nIf you installed via a package manager, `uninstall` removes everything it wrote and\ntells you the one command to finish removing the binary:\n\n```bash\nbrew uninstall lean-ctx        # Homebrew\ncargo uninstall lean-ctx       # cargo install\nnpm uninstall -g lean-ctx-bin  # npm\npi uninstall npm:pi-lean-ctx   # Pi Coding Agent\n```\n\n## Star History\n\n\u003ca href=\"https://star-history.com/#yvgude/lean-ctx\u0026Date\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=yvgude/lean-ctx\u0026type=Date\u0026theme=dark\" /\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=yvgude/lean-ctx\u0026type=Date\" /\u003e\n    \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=yvgude/lean-ctx\u0026type=Date\" /\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n## Contributing\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md). Easy first PR: propose a new CLI compression pattern via the [issue template](.github/ISSUE_TEMPLATE/compression_pattern.md).\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyvgude%2Flean-ctx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyvgude%2Flean-ctx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyvgude%2Flean-ctx/lists"}