Your system. The same context layer.

Choose your environment

The local CLI and MCP runtime have native releases for all three operating systems. Install LeanCTX where your AI tool executes: on your desktop, inside WSL, or on the remote Linux machine—not just on the computer displaying the editor.

Environment	Published native builds	Start here
Windows	x64, MSVC by default; GNU alternative	PowerShell quickstart
macOS	Apple Silicon (ARM64), Intel (x86_64)	macOS quickstart
Linux	x86_64 and ARM64; GNU and musl	Linux quickstart
WSL 2	Linux build matching the distribution’s architecture	Linux quickstart

This matrix reflects the 3.10.2 core release. A native Windows ARM64 archive is not published in that release. The standalone Linux installer selects GNU when it detects glibc 2.35 or newer and otherwise uses musl. Check the assets of your chosen release before installing a different version.

The SDK has a separate contract. SDK 1.1.0 Agent Tools pin Engine 3.10.1. Its published certification matrix lists Linux x86_64 GNU and macOS ARM64; native core availability does not certify the same platform for the SDK. See the SDK platform guidance.

Install without a package manager

Windows ZIP

Download lean-ctx-x86_64-pc-windows-msvc.zip and SHA256SUMS from the same release. The MSVC build is the standard Windows choice; the GNU archive is a separate alternative.

In PowerShell, from the folder containing the download:

Get-FileHash -LiteralPath .\lean-ctx-x86_64-pc-windows-msvc.zip -Algorithm SHA256

Compare the result with that filename’s entry in SHA256SUMS. Only continue when they match. Then extract the verified archive to a user-owned directory:

$leanctxInstall = Join-Path $env:LOCALAPPDATA "Programs\LeanCTX"
Expand-Archive -LiteralPath .\lean-ctx-x86_64-pc-windows-msvc.zip -DestinationPath $leanctxInstall -Force
& (Join-Path $leanctxInstall "lean-ctx.exe") --version

Add that directory to your user Path in Windows’ environment-variable settings, then reopen your terminal and AI tool. For the current PowerShell session, you can make it available immediately:

$env:Path = "$leanctxInstall;$env:Path"
lean-ctx --version

The repository’s install.ps1 is a build-from-source script: it requires a checkout and Rust. It is not a standalone binary-download command.

macOS and Linux archives

The standalone installer in the Linux quickstart also supports macOS. It installs to ~/.local/bin by default and does not require Homebrew or Node.js.

For a pinned or offline installation, download the .tar.gz for your architecture and SHA256SUMS from the same release. On macOS, use shasum -a 256; on Linux, use sha256sum. Compare the archive’s digest with its exact entry before extracting it. Place the executable in a user-owned directory on your PATH, such as ~/.local/bin.

The installer attempts checksum verification, but can skip it if no supported checksum tool is available. For a verified manual installation, stop if you cannot check the digest.

Use the right shell and paths

Examples labelled CLI · all platforms use the same LeanCTX arguments in PowerShell, Bash and zsh. Examples labelled Bash / zsh, POSIX shell or PowerShell use that shell’s syntax.

If you installed through npm on Windows, use the lean-ctx.cmd launcher in place of lean-ctx in these examples. It avoids PowerShell’s .ps1 execution-policy restrictions. A native ZIP installation provides lean-ctx.exe directly.

Task	PowerShell on Windows	Bash / zsh on macOS or Linux
Open a project	Set-Location "C:\work\my-project"	cd "$HOME/work/my-project"
Read an environment variable	$env:LEAN_CTX_CONFIG_DIR	$LEAN_CTX_CONFIG_DIR
Set one for the current shell	$env:LEAN_CTX_CONFIG_DIR = "C:\work\leanctx-config"	export LEAN_CTX_CONFIG_DIR="$HOME/work/leanctx-config"
Run a binary in this folder	.\lean-ctx.exe --version	./lean-ctx --version
Find the executable	Get-Command lean-ctx -All	command -v lean-ctx

Replace example directories with your own. Quote paths containing spaces. In JSON, escape Windows backslashes ("C:\\work\\my-project") or use forward slashes ("C:/work/my-project"). A quoted executable path in PowerShell needs the call operator: & "C:\path with spaces\lean-ctx.exe" --version.

CLI read commands accept project-relative paths. Run them from your intended project; don’t copy a macOS home directory or an author’s absolute path from a reference snapshot.

Find configuration and local data

LeanCTX uses XDG-style directories on Windows too. It does not default to AppData for its own configuration. On a fresh installation without overrides:

Purpose	macOS / Linux	Windows (PowerShell home notation)
Configuration	~/.config/lean-ctx/config.toml	$HOME\.config\lean-ctx\config.toml
Data	~/.local/share/lean-ctx	$HOME\.local\share\lean-ctx
State	~/.local/state/lean-ctx	$HOME\.local\state\lean-ctx
Cache	~/.cache/lean-ctx	$HOME\.cache\lean-ctx

Existing installations may retain legacy directories. LEAN_CTX_CONFIG_DIR, LEAN_CTX_DATA_DIR, LEAN_CTX_STATE_DIR, LEAN_CTX_CACHE_DIR and XDG environment overrides also affect resolution. A legacy data-directory override can influence more than one category. Ask the installed runtime instead of guessing:

lean-ctx config path
lean-ctx config validate

Your AI tool’s MCP configuration is separate. Let lean-ctx wrap or lean-ctx setup write the host-specific location and binary path. See configuration for individual settings.

Understand integration differences

Layer	macOS	Linux	Native Windows
Local CLI and MCP tools	Native runtime	Native runtime	Native x64 runtime
Automatic shell-output hooks	Bash / zsh when installed	Bash / zsh when installed	No Bash / zsh shell-hook installation
Agent-specific hooks	Depends on host integration	Depends on host integration	Depends on host integration; separate from shell hooks
Daemon / proxy login autostart	LaunchAgent	systemd user service, when available	No equivalent login-service installer in the reviewed runtime

On Windows, use MCP tools or explicit CLI calls for context-aware operations. A normal PowerShell command is not automatically compressed just because LeanCTX is installed. On Linux without a working systemd user session, do not assume a login service was installed successfully. Use lean-ctx status and lean-ctx doctor to inspect the result.

The optional request proxy is not required for CLI reads or MCP use. The absence of login autostart does not mean the Windows CLI cannot run. See shell output and proxy configuration for the relevant integration boundary.

WSL and remote development

Treat Windows and each WSL distribution as separate environments, with separate executables, home directories and configuration. If your agent runs inside WSL, install the Linux build there and run setup there. A Windows-hosted editor connected to WSL must launch its MCP server in the same intended environment; verify this in its MCP settings.

Use Linux paths for Linux processes. Keep the project in the environment where its tools run when practical; see Microsoft’s WSL filesystem guidance. The same principle applies to SSH hosts and development containers: install and verify inside that environment.

Update and reconnect

Use the installation method that owns your executable. Avoid installing a second copy just to update the first.

Homebrew on macOS:

brew update
brew upgrade lean-ctx

npm on Windows:

$env:LEAN_CTX_NO_ONBOARD = "1"
npm.cmd install -g lean-ctx-bin@latest
Remove-Item Env:LEAN_CTX_NO_ONBOARD
lean-ctx.cmd --version

Standalone installer on macOS / Linux: rerun the reviewed download-and-install commands from the quickstart. For a manual archive installation, replace the executable from a verified release in the same installation directory after closing processes that use it. The npm wrapper can download a different core version from its own package version; check the installed binary.

Restart your connected AI tool and verify:

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

If the binary location changed, rerun the corresponding wrapper or guided setup and review the host configuration. Keep SDK updates separate: preserve the companion version required by that SDK release.

To undo a host integration, use the corresponding lean-ctx unwrap command first. Removing an executable does not necessarily remove configuration, caches or project knowledge; keep those unless you intend to erase that local state.

Sources & versions9 references · Reviewed 17 Sept 2026

• install.shinstall.shReviewed checkout
• install.ps1install.ps1Reviewed checkout
• postinstall.jspackages/lean-ctx-bin/postinstall.jsReviewed checkout
• paths.rsrust/src/core/paths.rsReviewed checkout
• shell_hook.rsrust/src/shell_hook.rsReviewed checkout
• daemon_autostart.rsrust/src/daemon_autostart.rsReviewed checkout
• proxy_autostart.rsrust/src/proxy_autostart.rsReviewed checkout
• release.yml.github/workflows/release.ymlReviewed checkout
• COMPATIBILITY.mdSDK / COMPATIBILITY.mdGitHub

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