# lean-ctx — Context Runtime (MCP + Shell Hook)

> lean-ctx is a local-first context runtime (MCP + shell hook) that compresses file reads and CLI output to cut token waste for coding agents.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

```bash
curl -fsSL https://leanctx.com/install.sh | sh
lean-ctx setup
lean-ctx doctor
lean-ctx gain --live
```

## Intro

lean-ctx is a local-first context runtime (MCP + shell hook) that compresses file reads and CLI output to cut token waste for coding agents.

**Best for:** Developers with shell-heavy AI sessions who want lower token burn

**Works with:** Rust binary, MCP clients, Cursor/Codex/Claude Code integrations

**Setup time:** 4-10 minutes

### Key facts (verified)

- GitHub: 1611 stars · 165 forks · pushed 2026-05-13.
- License: Apache-2.0 · owner avatar + repo URL verified via GitHub API.
- README-verified entrypoint: `curl -fsSL https://leanctx.com/install.sh | sh`.

## Main

- Start with `lean-ctx setup` + `doctor` to ensure the MCP server and shell hook are actually active for your agent/editor.

- Use read modes intentionally: map/signatures/diff modes reduce tokens while still giving enough context for refactors.

- If you share a repo across containers/workspaces, follow the README guidance on repo IDs (`.lean-ctx-id`) to avoid cache/context collisions.

### Source-backed notes

- README headline claims 60–95% token reduction (up to 99% on cached reads) and lists 59 tools and 10 read modes.
- README provides a 60-second install flow: install → `lean-ctx setup` → `lean-ctx doctor` → `lean-ctx gain --live`.
- README includes a compatibility matrix with agent-specific init commands like `lean-ctx init --agent codex` and `... --agent claude`.

### FAQ

- **Is this only an MCP server?**: No — README describes both an MCP server and a shell hook that compresses CLI output.
- **Can I disable it quickly?**: Yes — README lists an immediate disable command (`lean-ctx-off`) for the current shell.
- **What’s a safe first workflow?**: Run `gain --live` while doing normal dev tasks to see token savings before changing read modes.

## Source & Thanks

> Source: https://github.com/yvgude/lean-ctx
> License: Apache-2.0
> GitHub stars: 1611 · forks: 165

---

<!-- ZH -->

## Quick Use

```bash
curl -fsSL https://leanctx.com/install.sh | sh
lean-ctx setup
lean-ctx doctor
lean-ctx gain --live
```

## Intro

lean-ctx 是面向 AI 编码 agent 的本地上下文层：在内容进入模型前压缩文件读取与命令行输出。README 提到可减少 60–95% token，并提供 59 个工具与 10 种读取模式。

**Best for:** 经常让 AI 跑 git/测试/构建，想显著减少 token 浪费的开发者

**Works with:** Rust 单文件二进制；MCP 客户端；Cursor/Codex/Claude Code 集成

**Setup time:** 4-10 minutes

### Key facts (verified)

- GitHub：1611 stars · 165 forks；最近更新 2026-05-13。
- 许可证：Apache-2.0；作者头像与仓库链接均已通过 GitHub API 复核。
- README 中核对过的入口命令：`curl -fsSL https://leanctx.com/install.sh | sh`。

## Main

- 先跑 `lean-ctx setup` + `doctor`，确认 MCP 与 shell hook 在你的 agent/editor 里真的生效。

- 按需选择读取模式：map/signatures/diff 等模式能显著省 token，同时保留重构所需的关键信息。

- 跨容器/多工作区共享仓库时，按 README 建议用 `.lean-ctx-id` 区分项目，避免缓存/上下文串库。

### Source-backed notes

- README 标题区写明：可减少 60–95% token（缓存读取最高到 99%），并列出 59 tools / 10 read modes。
- README 给出 60 秒上手流程：安装 → `lean-ctx setup` → `lean-ctx doctor` → `lean-ctx gain --live`。
- README 提供兼容矩阵，并给出按 agent 初始化的命令，如 `lean-ctx init --agent codex` / `... --agent claude`。

### FAQ

- **它只是 MCP server 吗？**：不止。README 说明它同时包含 MCP server 与压缩命令行输出的 shell hook。
- **能不能快速停用？**：可以。README 的 Troubleshooting 区域给了当前 shell 立即停用命令 `lean-ctx-off`。
- **新手怎么安全开始？**：先在日常开发中开 `gain --live` 观察节省效果，再逐步引入不同读取模式。

## Source & Thanks

> Source: https://github.com/yvgude/lean-ctx
> License: Apache-2.0
> GitHub stars: 1611 · forks: 165


---
Source: https://tokrepo.com/en/workflows/lean-ctx-context-runtime-mcp-shell-hook
Author: MCP Hub