pi-lean-ctx

Pi Coding Agent extension that provides ctx_-prefixed tools backed by lean-ctx for 60–90% token savings.

• Default: embedded MCP bridge ON (persistent session cache → unchanged re-reads cost ~13 tokens), additive mode (Pi builtins preserved)
• Opt out: LEAN_CTX_PI_ENABLE_MCP=0 (or "enableMcp": false) forces the one-shot CLI path, which cannot cache across calls
• Optional: replace mode (LEAN_CTX_PI_MODE=replace) disables Pi builtins

Tool Mode

By default, pi-lean-ctx runs in additive mode: Pi's built-in tools (read, bash, ls, find, grep) remain available alongside the ctx_* tools. Agents can use either set.

To switch to replace mode (disables Pi builtins, only ctx_* tools available):

export LEAN_CTX_PI_MODE=replace

Config file

If you only use lean-ctx through Pi, keep every setting in one file instead of env vars — ~/.pi/agent/extensions/pi-lean-ctx/config.json:

{
  "mode": "replace",
  "enableMcp": true,
  "binary": "/opt/lean-ctx/bin/lean-ctx",
  "env": { "LEAN_CTX_COMPRESSION": "aggressive" }
}

mode → LEAN_CTX_PI_MODE, enableMcp → LEAN_CTX_PI_ENABLE_MCP, binary → LEAN_CTX_BIN, disableTools → LEAN_CTX_PI_DISABLE_TOOLS, toolPrefix → LEAN_CTX_PI_TOOL_PREFIX (see Coexisting with AFT and magic-context). The env map is forwarded to every lean-ctx subprocess, so it can override ~/.lean-ctx/config.toml engine settings. Explicit env vars still win over the file; the file wins over defaults. The deny-list is the one exception — the env and file lists are merged, since a deny-list is additive by intent.

What it does

ctx_ Tools (CLI-backed)

Adds ctx_-prefixed tools alongside Pi's builtins (or replaces them in replace mode):

Pi's edit and write builtins remain unchanged.

Direct lean-ctx CLI tool

The lean_ctx tool runs lean-ctx directly (no nested compression). Use it for commands like:

• lean_ctx overview
• lean_ctx session …
• lean_ctx knowledge …
• lean_ctx gain / lean_ctx stats
• lean_ctx index …

Optional MCP Tools (Embedded Bridge)

By default, pi-lean-ctx does not start an MCP server. If enabled, it spawns lean-ctx as an MCP server and registers advanced tools directly in Pi:

If you don't want MCP: keep it disabled and use the ctx_ CLI tools + lean_ctx tool only.

Install

# 1. Install lean-ctx (if not already installed)
cargo install lean-ctx
# or: brew tap yvgude/lean-ctx && brew install lean-ctx

# 2. Install the Pi package
pi install npm:pi-lean-ctx

# 3. Restart Pi

Or use the automated setup:

lean-ctx init --agent pi

How it works

ctx_ tools (CLI-backed)

These tools invoke the lean-ctx binary via CLI with LEAN_CTX_COMPRESS=1. The built-in tools they replace (read, bash, ls, find, grep) are disabled via pi.setActiveTools() so only the ctx_ versions are available to the LLM.

Embedded MCP bridge (session cache + advanced tools)

On by default, pi-lean-ctx spawns the lean-ctx binary as an MCP server (JSON-RPC over stdio). This persistent process holds the session cache: ctx_read (every mode, including line ranges) is routed through the bridge, so an unchanged re-read costs ~13 tokens instead of the full file and the read registers as a real CEP session (counted by lean-ctx gain). The bridge also discovers the server's advanced tools (ctx_edit, ctx_overview, ctx_graph, …), filters out those already exposed as ctx_ CLI tools, and registers the rest as native Pi tools.

The bridge wins over ~/.pi/agent/mcp.json: a lean-ctx entry there (written by lean-ctx init --agent pi) does not disable the embedded bridge, because Pi has no native MCP support and that entry only does anything if you separately run pi-mcp-adapter. /lean-ctx warns about possible duplicates only when the adapter is genuinely running. If the bridge can't start, the CLI path keeps working — only the cache and advanced tools are unavailable.

Automatic reconnection

If the MCP server process crashes, the bridge automatically reconnects (up to 3 attempts with exponential backoff). If reconnection fails, CLI-based tools continue working normally — only the advanced MCP tools become unavailable.

Disabling the bridge (optional)

The bridge is on by default. To force the one-shot CLI path (no cross-call cache), set an environment variable and restart Pi:

export LEAN_CTX_PI_ENABLE_MCP=0
pi

…or set "enableMcp": false in ~/.pi/agent/extensions/pi-lean-ctx/config.json.

Verifying token savings

The session cache's headline claim — an unchanged re-read costs ~13 tokens — is now a one-command, machine-checkable self-test (issue #361). No manual transcript inspection required:

lean-ctx verify-cache

It reads a file twice through the real session cache and asserts the second read collapses to a [unchanged …] stub:

lean-ctx verify-cache

  Target:        src/main.rs
  Cache policy:  aggressive
  Read #1 (full):     3731 tokens
  Read #2 (re-read):  13 tokens  [unchanged stub]
  Re-read savings:    100%
  Cache hits (run):   1/2
  CEP sessions:       42 (88% cross-call hit ratio)

  PASS — session cache engaged: the unchanged re-read cost 13 tokens (≈13-token stub).

• Exit code 0 = cache proven, 1 = no stub (cache not engaging), 2 = stubbing disabled by config (e.g. cache_policy = safe). Add --json for CI.
• Pass an explicit path to probe a real file: lean-ctx verify-cache src/app.ts.
• lean-ctx doctor also prints a Session cache line (CEP sessions + cross-call hit ratio) so you can answer "is the cache engaging?" at a glance.

On Pi specifically, the embedded MCP bridge (on by default) is what holds the cache across calls. If verify-cache fails, confirm the bridge is connected via /lean-ctx; the one-shot CLI path cannot cache across calls.

This check was added in response to the independent, pre-registered tokbench benchmark, where the ~13-token re-read previously had to be verified by hand.

pi-mcp-adapter compatibility

If you prefer using pi-mcp-adapter to manage your MCP servers, lean-ctx integrates automatically:

# Option A: lean-ctx writes the config for you
lean-ctx init --agent pi

# Option B: Manual configuration in ~/.pi/agent/mcp.json

{
  "mcpServers": {
    "lean-ctx": {
      "command": "/path/to/lean-ctx",
      "lifecycle": "lazy",
      "directTools": true
    }
  }
}

When pi-mcp-adapter manages the lean-ctx MCP server, pi-lean-ctx detects this and only registers its CLI-based tool overrides, leaving MCP tool management to the adapter.

Binary Resolution

The extension locates the lean-ctx binary in this order:

1. LEAN_CTX_BIN environment variable
2. binary in ~/.pi/agent/extensions/pi-lean-ctx/config.json
3. ~/.cargo/bin/lean-ctx
4. ~/.local/bin/lean-ctx (Linux) or %APPDATA%\Local\lean-ctx\lean-ctx.exe (Windows)
5. /usr/local/bin/lean-ctx (macOS/Linux)
6. lean-ctx on PATH

Smart Read Modes

The ctx_read tool automatically selects the optimal lean-ctx mode:

Slash Command

Use /lean-ctx in Pi to check:

• Which binary is being used
• MCP bridge status (disabled / embedded / adapter)
• Active ctx_ tool names
• Coexistence info (#359): active tool prefix, tools handed to other extensions (Disabled), and tools skipped due to a name already taken (Skipped)

Disabling specific tools

To disable specific MCP tools, configure disabled_tools in ~/.lean-ctx/config.toml:

disabled_tools = ["ctx_graph", "ctx_benchmark"]

Or via environment variable:

LEAN_CTX_DISABLED_TOOLS=ctx_graph,ctx_benchmark pi

Coexisting with AFT and magic-context

pi-lean-ctx is built to stack with other Pi extensions such as AFT and magic-context (issue #359).

No more load crashes. If another extension already registered a tool name (e.g. magic-context's ctx_expand), pi-lean-ctx now skips that tool with a warning instead of crashing the whole agent. The rest of lean-ctx keeps working. Run /lean-ctx to see exactly which tools were skipped.

Hand tool names to another extension

Use a deny-list so the other extension owns shared names while lean-ctx keeps its compression + session-cache core (ctx_read, ctx_shell, …):

# env: comma/space separated, case-insensitive
export LEAN_CTX_PI_DISABLE_TOOLS="ctx_memory,ctx_expand,ctx_search"

…or in ~/.pi/agent/extensions/pi-lean-ctx/config.json (merged with the env list):

{
  "disableTools": ["ctx_memory", "ctx_expand", "ctx_search"]
}

This is the Pi-extension deny-list — it controls which tools lean-ctx registers in Pi (including its own ctx_* tools like ctx_grep). It is separate from the engine-level disabled_tools / LEAN_CTX_DISABLED_TOOLS, which hides tools from the MCP server itself.

Or namespace them with a prefix

Keep every tool but expose the bridge tools under your own prefix, so nothing collides and small models see no duplicate names:

export LEAN_CTX_PI_TOOL_PREFIX="lc_"   # ctx_expand → lc_ctx_expand

The signature tools (ctx_read, ctx_shell, ctx_ls, ctx_find, ctx_grep) keep their stable names; only the bridge-discovered MCP tools are prefixed.

Curated profile (recommended division of labor)

Copy-paste config for the profile above (~/.pi/agent/extensions/pi-lean-ctx/config.json):

{
  "mode": "additive",
  "enableMcp": true,
  "disableTools": ["ctx_memory", "ctx_expand", "ctx_search"]
}

Result: no duplicate search/memory tools in the tool list, no load crash, and each extension does what it is best at. Verify with /lean-ctx, which now lists the active prefix plus any handed-off (Disabled) and skipped tools.

Links

• lean-ctx — the Cognitive Context Layer for AI coding agents
• GitHub
• Discord