Connect Claude Code.

Install where the host runs

Follow the installation guide for Windows, macOS or Linux. The runtime must be available in the environment that executes your AI tool. A Windows installation and one inside WSL are separate setups.

Confirm the binary before changing host configuration:

lean-ctx --version
lean-ctx status

Register the integration

lean-ctx wrap claude

The wrapper configures supported integration pieces and reports verification results. Shell hooks and login services differ by platform; native Windows does not acquire Unix shell hooks.

Open a new Claude Code session after registration. Confirm that the session exposes LeanCTX tools before assuming its file or shell operations are covered.

Verify the actual path

Ask the host to locate a file in your project and read its signatures with ctx_read. Inspect the tool invocation, selected path and returned representation.

Then request the relevant implementation with an explicit line range or a fresh full read. A successful response demonstrates that particular call path; it does not mean every future operation uses LeanCTX.

Keep exact file contents for edits. A signatures view explains an interface and can omit the implementation that must be changed.

See what passes the gateway

Where Claude Code 2.1.287 or newer is installed, lean-ctx setup and lean-ctx update also set up the LeanCTX plugin for Claude Code and say so in their report. It applies in new Claude Code sessions, or after /reload-plugins.

The plugin adds a docked cockpit in the gateway’s own terms:

• Claude saw: the sources that reached Claude, how deep (structure, passage, full file, search, command), and which went through LeanCTX rather than one of Claude’s own tools.
• Tokens: what stayed out of Claude’s context, against the raw tool output, and the context budget in use.
• Two checks: may it be read, may it be delivered. Blocked paths and commands, redacted secrets, flagged injections.
• Receipts: the savings ledger and audit trail, re-verified in the background with lean-ctx value, and the last calls with their depth and decision.

A line above the prompt shows calls passing the gateway while Claude works. The status line below the prompt keeps the totals for this conversation’s session:

◆ LeanCTX │ SELECT 12 files · 30 commands │ CONTROL ⛨ 3 enforced │ TOKENS −1.2M kept out · 60% leaner

The numbers come from the LeanCTX session serving this conversation, even when other agents use LeanCTX in the same project. They describe what the integration observed; they are not a cost or quality result.

The plugin runs inside Claude Code with your permissions. Remove it with:

lean-ctx claude-mod uninstall

A removal is kept: later setups and updates do not reinstall it. lean-ctx claude-mod install brings it back.

Diagnose a missing connection

lean-ctx doctor

Check the wrapper report, host restart, executable location and project scope. An already-running desktop process may not inherit a changed terminal environment. For WSL, check both where the host runs and where LeanCTX was installed.

Use the troubleshooting guide before manually replacing configuration. Preserve unrelated host settings.

Remove the integration

lean-ctx unwrap claude

Unwrapping removes the supported integration configuration. It is different from uninstalling the binary or deleting retained project knowledge.

Sources & versions6 references · Reviewed 17 Sept 2026

• 01-setup-and-onboarding.mddocs/reference/01-setup-and-onboarding.mdReviewed checkout
• wrap_cmd.rsrust/src/cli/wrap_cmd.rsReviewed checkout
• mode.rsrust/src/tools/ctx_read/mode.rsReviewed checkout
• README.mdintegrations/claude-code-mod/README.mdReviewed checkout
• claude_mod.rsrust/src/hooks/agents/claude_mod.rsReviewed checkout
• value-display.mddocs/guides/value-display.mdReviewed checkout

Core checkout

0ce2207ee4

Reviewed runtime

3.10.2

SDK release

1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility