Skip to content
Docs
Website
Documentation

Protect & operate

Find the cause before changing the setup.

Start with the failing layer: host connection, access, retrieval, output or SDK compatibility.

AvailableReviewed September 2026

Establish a baseline

lean-ctx --version
lean-ctx status
lean-ctx doctor

Record the exact error, operating system, CPU architecture, shell and command or tool that produced it. Note whether the process runs natively, in WSL, in a container or over SSH. doctor without repair flags is the first diagnostic step; do not begin with a reset.

The command is not found

First check which executable your terminal can find.

Windows / PowerShell:

Get-Command lean-ctx -All

macOS / Linux — Bash or zsh:

command -v lean-ctx

If none is found, add the installation directory to your user PATH and open a new terminal. Restart the editor too: it may still have an older environment. For npm, npm.cmd prefix -g on Windows shows the global installation prefix. For the standalone Unix installer, the default executable is ~/.local/bin/lean-ctx. See installation and paths.

If several versions exist, update the installation actually used by your host rather than adding another copy. The binary path in its MCP configuration may differ from your terminal’s PATH.

lean-ctx update fails with “missing its integrity digest”

ERROR lean_ctx::core::updater::flow: Failed to complete durable update transaction: prepared transaction is missing its integrity digest

The built-in updater of 3.11.0 and 3.11.1 stops at this point after it has downloaded and verified a release. Scheduled automatic updates fail the same way. Nothing is changed: the installed binary keeps running, and every attempt cleans up after itself. The fault is in the updater of the installed version, so it cannot repair itself; update once through the channel you installed with:

curl -fsSL https://leanctx.com/install.sh | sh   # standalone install in ~/.local/bin
brew upgrade lean-ctx                            # Homebrew
npm i -g lean-ctx-bin@latest                     # npm
cargo install lean-ctx --force                   # cargo

On Arch, update lean-ctx or lean-ctx-bin with your AUR helper. On Windows without npm, extract the latest release’s ZIP over your existing lean-ctx.exe as described under installation without a package manager. Then run lean-ctx --version and restart your editor or agent so it loads the new binary. From 3.11.2 on, lean-ctx update and automatic updates work again, including after such a reinstall.

Windows installation or shell errors

  • npm.ps1 or lean-ctx.ps1 cannot be loaded: use npm.cmd to install and lean-ctx.cmd to run the npm installation. For example, lean-ctx.cmd doctor runs the diagnostic. Do not disable your execution policy just to use these launchers.
  • An archive will not run: check that it is the x64 Windows build, not a Linux or macOS archive. Recheck its digest against the same release’s SHA256SUMS.
  • lean-ctx update or enable-gpu says “cosign is unavailable; refusing unsigned release”: the 3.11.0 updater needs the external cosign tool under exactly that name. Installing it does not help: the 3.11.0 updater then stops at the integrity-digest error. Extract the latest release’s Windows ZIP over your lean-ctx.exe, or run npm i -g lean-ctx-bin@latest for an npm installation. From 3.11.1 no extra tool is needed, and from 3.11.2 lean-ctx update works again.
  • A path with spaces fails: quote it and use PowerShell’s & operator for a quoted executable. Use .\lean-ctx.exe for a binary in the current folder.
  • PowerShell commands produce no LeanCTX metrics: installing the runtime does not install Unix shell hooks on Windows. Use a connected MCP tool or an explicit lean-ctx -c call for a supported command.

For native-versus-WSL mismatches, check that the binary, project and MCP host all belong to the intended environment. Windows paths and Linux paths are not interchangeable.

Linux or macOS installation errors

  • GLIBC_x.y not found: use the matching musl release on Linux or let the standalone installer choose the correct variant. Do not replace system glibc to satisfy this binary.
  • Exec format error / wrong architecture: compare the artifact with uname -m; macOS and Linux archives are different even when both use ARM64.
  • A login service is unavailable: Linux autostart uses a systemd user service. Containers and minimal distributions may not provide a working user session. This differs from the macOS LaunchAgent setup.
  • The operating system blocks an executable: verify the release source and checksum, then review the operating system’s security message. Do not turn off system-wide protections as an installation step.

Tools do not appear in the host

Check the host’s MCP connection and logs, verify the configured binary path, and restart the host after setup. The active tool profile may expose only a subset of the registry.

Do not add a second conflicting MCP entry just because a tool is hidden. Compare the host configuration with its supported setup path.

For a remote or WSL-hosted agent, run the diagnostics in that environment. A successful command in your desktop terminal does not prove that a remote MCP process can find the same binary.

A file is refused

The refusal names the command that admits the path, usually lean-ctx allow-path <dir>. It takes effect without a restart. Check the resolved path first: an allowed filename can still resolve through a symlink outside the boundary.

If the agent works in the wrong repository, run lean-ctx doctor. “Project binding” reports a LEAN_CTX_PROJECT_ROOT pinned in a global agent configuration. lean-ctx doctor --fix removes it; restart the agent once afterwards.

Use security to understand the layer that refused the operation.

A shell redirect is refused

From 3.11.1, ctx_shell output capture (> build.log, >> notes.txt, | tee out.txt) may write into the session’s project, directories in allow_paths or extra_roots, directories in write_allow_paths, and scratch paths such as /tmp. Other destinations are refused, and so are /, your home directory and read_only_roots. Up to 3.11.4, downloads (curl -o, wget, dd of=) may only write into scratch paths; releases after 3.11.4 let them write wherever output capture may, judged where the file lands. shell_allow_writes = true turns the capture check off.

A build binary is stale

Before 3.11.1, cargo build and cargo test run through ctx_shell wrote to a shared target directory under the LeanCTX data directory instead of ./target, so a binary started from ./target could be out of date. From 3.11.1 builds use the project’s own target directory again and are neither queued nor limited. The previous behavior is opt-in under [agents] in config.toml: shared_cargo_target, serialize_build_commands and cargo_build_jobs. An explicit CARGO_TARGET_DIR always wins.

A file comes back shortened

An automatic read can return a structural view of a long file. Agent instruction files are always delivered complete: AGENTS.md, SKILL.md, CLAUDE.md, CLAUDE.local.md, GEMINI.md, copilot-instructions.md, .cursorrules, .clinerules, .windsurfrules, and documents under skills/, .cursor/rules/, .claude/rules/, .claude/agents/ and .claude/commands/ (CLAUDE.md and the newer names from 3.11.1). For other files, request mode="full", or list them in redirect_exclude (globs such as "docs/**" or "*.json") in ~/.lean-ctx/config.toml: from 3.11.1 matching paths bypass the native-read redirect and are returned in full by automatic reads. LEAN_CTX_HOOK_EXCLUDE (comma-separated) overrides the configured list. Excluded paths skip the redaction the redirect applies, so from 3.11.2 a repository’s own .lean-ctx.toml can add entries only after you run lean-ctx trust for it; an untrusted workspace’s list is ignored with a [SECURITY] warning.

A read is only a reference

An unchanged re-read can return a cache reference; a large result can be archived. Request a focused fresh read or follow the returned recovery identifier.

If an archive has expired or the source is no longer accessible, recovery may fail. State the missing evidence and retrieve a current source when possible.

Search misses a known symbol

Confirm the root, ignore patterns and index state. Try a narrow regex search against the expected directory. Semantic ranking and graph extraction depend on the available index and language support.

Use the current ctx_search actions instead of relying on deprecated standalone aliases.

Session recall looks wrong

Check that both sessions used the same intended project. Inspect the saved session rather than assuming that host chat history was imported.

lean-ctx sessions doctor

Review proposed repairs before using a fix flag. A knowledge fact can be retained and still be outdated.

SDK rejects the Engine

Check the exact SDK release, companion artifact and negotiated interface/schema/transport. A newer installed CLI is not evidence of compatibility. Use the declared companion from the SDK quickstart.

LeanCTX processes use a lot of memory

Find out which process holds it. lean-ctx mcp processes belong to agent hosts; lean-ctx serve --_foreground-daemon is the shared background daemon.

ps -axo pid,rss,etime,command | grep '[l]ean-ctx'
lean-ctx daemon status

Up to 3.11.4, the daemon kept growing with every project root it indexed and returned little to the operating system, so many repositories or worktrees could take it past a gigabyte. Releases after 3.11.4 return freed memory, keep search indexes for at most eight roots and cap the daemon at daemon_max_rss_mb (2048 MB). On 3.11.4 and earlier, lean-ctx daemon restart releases what the daemon holds. Each MCP server has its own target, mcp_max_rss_mb (512 MB); see performance tuning.

If one process keeps growing while idle, record its memory twice, about 30 minutes apart (on macOS, vmmap --summary <pid> and footprint <pid>), and include both in your report.

Report a reproducible issue

Include versions, platform, the failing operation and a small non-sensitive example. Redact credentials and private source from logs before sharing them through support.

Sources & versions5 references Reviewed
Core checkout
0ce2207ee4
Installed 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