yvgude--lean-ctx/docs/guides/claude-code.md

Claude Code + lean-ctx Integration Guide

Complete guide to setting up and optimally using lean-ctx with Claude Code (Anthropic's CLI coding agent).

Overview

Property	Value
Integration mode	Hybrid (MCP reads + shell hooks)
Config file	~/.claude.json
Instructions	<!-- lean-ctx --> block in ~/.claude/CLAUDE.md
Skill file	~/.claude/skills/lean-ctx/SKILL.md (loads on demand)
Setup command	lean-ctx init --agent claude

Since 3.8: there is no ~/.claude/rules/lean-ctx.md anymore. Claude Code loads every rules file unconditionally at session start, which duplicated the instructions in each session (12k+ token memory footprints). lean-ctx setup removes the legacy file and maintains a compact block in ~/.claude/CLAUDE.md instead; detail docs live in the on-demand skill.

Quick Setup

# One command — configures MCP, rules, shell hook, and skill
lean-ctx init --agent claude

# Verify
lean-ctx doctor

That's it. lean-ctx auto-detects Claude Code by checking for the claude binary in $PATH or the existence of ~/.claude.json / ~/.claude/.

Manual Setup

If you prefer manual configuration or need to customize the setup.

Step 1: MCP Server Registration

lean-ctx registers itself via claude mcp add-json --scope user when available. The resulting entry in ~/.claude.json:

{
  "mcpServers": {
    "lean-ctx": {
      "command": "lean-ctx",
      "autoApprove": [
        "ctx_read",
        "ctx_shell",
        "ctx_search",
        "ctx_tree",
        "ctx_overview",
        "ctx_preload",
        "ctx_compress",
        "ctx_metrics",
        "ctx_session",
        "ctx_knowledge",
        "ctx_agent",
        "ctx_share",
        "ctx_analyze",
        "ctx_semantic_search",
        "ctx_graph",
        "ctx_refactor",
        "ctx_expand",
        "ctx_impact",
        "ctx_review",
        "ctx_pack"
      ]
    }
  }
}

Note

: The autoApprove list includes all read-only and safe tools so Claude Code doesn't prompt for confirmation on every call. lean-ctx supports 80 tools total — the full list is auto-configured.

If claude mcp add-json is not available (older Claude Code versions), lean-ctx falls back to directly writing ~/.claude.json.

Step 2: Agent Instructions (CLAUDE.md block + skill)

lean-ctx maintains a marker-delimited block in ~/.claude/CLAUDE.md:

<!-- lean-ctx -->
<!-- lean-ctx-claude-v6 -->
## lean-ctx — Context Runtime

When the `ctx_*` MCP tools are listed in this session, prefer them over native equivalents:
- `ctx_read` instead of `Read` / `cat` for exploration (cached, 10 modes, re-reads ~13 tokens)
- `ctx_shell` instead of `bash` / `Shell` (95+ compression patterns)
- `ctx_search` instead of `Grep` / `rg` (compact results)
- `ctx_tree` instead of `ls` / `find` (compact directory maps)
- Edits: `ctx_read(mode="anchored")` → `ctx_patch` (line+hash anchors, never echo old text; `op=create` for new files). `ctx_edit` (str_replace) is the legacy power-profile fallback.

Native `Read` → `Edit`/`StrReplace` stays fully supported — the edit gate requires a
prior native Read of the same file path. Write, Delete, Glob — use normally.
If no `ctx_*` tools are listed in this session, use the native tools throughout.

Read modes: anchored (edit), full (verbatim), map (overview), signatures (API), diff (post-edit), lines:N-M (range), auto.
Details live in the `lean-ctx` skill (loads on demand — keep this file lean).
<!-- /lean-ctx -->

The v5 wording routes edits to the anchored editor (ctx_patch is advertised in the lazy core for Claude Code) while keeping v4's guard semantics: Claude Code enforces a path-keyed read-before-write gate on Edit/Write, so a natively-edited file must have been read with the native Read tool (lean-ctx's read_redirect = auto keeps that gate intact, see #637). And in sessions where the lean-ctx MCP server is not connected, no ctx_* tools exist — the block says explicitly to fall back to native tools instead of chasing unavailable ones.

Detail documentation (mode selection, session memory, proactive tools) lives in the skill at ~/.claude/skills/lean-ctx/SKILL.md, which Claude loads only when needed.

Both are written automatically:

lean-ctx setup

If a legacy ~/.claude/rules/lean-ctx.md from an older install still exists, setup removes it (it would be loaded in every session on top of the CLAUDE.md block).

Step 3: Shell Hook

Claude Code has shell access, so lean-ctx installs compression hooks for common commands:

# Activate shell hook (done by lean-ctx setup)
lean-ctx init --global

This enables transparent compression for 56 pattern modules (git, npm, cargo, docker, kubectl, terraform, and more).

Read compression under the read-before-write gate

Two settings work together so Claude Code keeps its native edit safety and the re-read savings:

• read_redirect = auto (default): on guard hosts (Claude Code / CodeBuddy) the PreToolUse Read redirect stays off, so the native Read runs on the real path and the path-keyed read-before-write gate records it — native Edit/Write keep working (#637).
• read_dedup = auto (default): a PostToolUse hook (lean-ctx hook read-dedup, matcher Read only) replaces the result of a re-read of an unchanged file with a compact [unchanged] stub via the documented updatedToolOutput channel. First reads stay byte-identical (edit safety: old_string always comes from real content), the file and the gate are untouched, and every failure path passes the original result through. Set read_dedup = off to disable, or on to dedup on every host.

Step 4: SKILL.md (Optional)

lean-ctx installs a skill file at ~/.claude/skills/lean-ctx/SKILL.md that provides Claude Code with detailed knowledge about all lean-ctx capabilities, modes, and best practices.

Optimal Workflow

Session Start

When Claude Code starts a new session, it should:

1. Call ctx_overview(task) — fast project orientation with task-relevant context
2. Use ctx_read(path, "map") for context files — dependencies, exports, key signatures
3. Use ctx_read(path, "full") only for files it will edit

During Development

Read file for context    → ctx_read("src/auth.rs", "map")
Read file to edit        → ctx_read("src/auth.rs", "full")
Re-read after editing    → ctx_read("src/auth.rs", "diff")
Search for patterns      → ctx_search("fn authenticate", "src/")
Run shell commands       → Uses shell hook automatically (or ctx_shell)
Find by meaning          → ctx_semantic_search("how does auth work?")
Check code relationships → ctx_graph("impact", "src/auth.rs")

Session Documentation

After significant work (implementation, bugfix, refactoring):

ctx_knowledge(action="remember", category="decision", content="Chose JWT over sessions for stateless auth")
ctx_session(action="task", value="Implement auth module [75%]")

When lean-ctx emits [CHECKPOINT] (after 30+ tool calls without documentation):

ctx_session(action="task", value="Current task status description")

Context Management

When context grows large  → ctx_compress (creates memory checkpoint)
Check token savings       → ctx_metrics
Per-tool cost breakdown   → ctx_cost
File-level savings        → ctx_heatmap

Multi-Agent Handoff

Claude Code supports multi-agent workflows via lean-ctx:

# Agent A records findings
ctx_knowledge(action="remember", category="insight", content="Config parsing uses TOML with JSONC fallback")

# Agent A hands off to Agent B
ctx_agent(action="handoff", target="agent-b", context="Continue implementing the config migration")

# Agent B receives context and continues
ctx_agent(action="sync")

The knowledge graph and session state persist across agents, so Agent B sees all of Agent A's discoveries and decisions.

Knowledge Persistence

lean-ctx maintains a temporal knowledge graph that survives across sessions:

# Remember a decision
ctx_knowledge(action="remember", category="decision", content="Use connection pooling with max 10 connections")

# Recall later (even in a new session)
ctx_knowledge(action="recall", query="connection pooling")

# Search knowledge by time
ctx_knowledge(action="timeline", range="today")

# Full-text search across all knowledge
ctx_knowledge(action="search", query="database configuration")

Knowledge categories: decision, discovery, blocker, progress, insight.

Advanced Configuration

Project-Level Config

Create .lean-ctx.toml in your project root to override global settings:

# Project-specific lean-ctx configuration
shell_activation = "always"      # or "agents-only"

Per-Project Rules

In addition to the global block in ~/.claude/CLAUDE.md, you can add project-specific rules in CLAUDE.md at your project root. lean-ctx will append its shared rules section if not already present.

CLAUDE.md Integration

If you have a project-level CLAUDE.md, lean-ctx can inject its rules there too using the SharedMarkdown format:

# Your existing project rules here
...

# lean-ctx — Context Engineering Layer
<!-- lean-ctx-rules -->
## Mode Selection
- Editing the file? → `full` first, then `diff` for re-reads
- Context only? → `map` or `signatures`
...
<!-- /lean-ctx -->

The section between <!-- lean-ctx-rules --> and <!-- /lean-ctx --> is managed by lean-ctx and auto-updated.

Troubleshooting

MCP server not connecting

# Check if lean-ctx is in PATH
which lean-ctx

# Verify MCP config
cat ~/.claude.json | python3 -m json.tool

# Test MCP server directly
echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}' | lean-ctx mcp

# Re-run setup
lean-ctx init --agent claude

Instructions not being applied

# Check the CLAUDE.md block exists
grep -A2 'lean-ctx' ~/.claude/CLAUDE.md

# Check the on-demand skill exists
ls ~/.claude/skills/lean-ctx/SKILL.md

# Reinstall block + skill
lean-ctx setup

Shell compression not working

# Check if shell hook is active
echo $LEAN_CTX_ACTIVE

# Re-install shell hook
lean-ctx init --global

# Restart your shell
exec $SHELL

claude mcp add-json fails

This can happen if the Claude Code binary is in an untrusted path. Options:

# Trust the path explicitly
export LEAN_CTX_TRUST_CLAUDE_PATH=1
lean-ctx init --agent claude

# Or set up manually by editing ~/.claude.json directly

High token usage despite lean-ctx

# Check if agent is using lean-ctx tools
lean-ctx gain --live

# Verify the agent sees the rules
# In Claude Code, check that ctx_read is being used instead of native Read

CLI Integration

Claude Code also benefits from lean-ctx's CLI compression when running shell commands:

# These commands are automatically compressed when run through Claude Code:
git status                    # ~800 → ~120 tokens
git log --oneline -20         # ~600 → ~150 tokens
cargo test                    # ~2000 → ~300 tokens
npm install                   # ~1500 → ~200 tokens
docker ps                     # ~400 → ~80 tokens

The shell hook intercepts these commands transparently — no changes needed to how Claude Code invokes them.

Further Reading

• lean-ctx Tools Reference
• CLI Reference
• Session Memory Guide
• Claude Code Documentation