Lean Ctx

https://github.com/yvgude/lean-ctx
Admin
Lean Ctx is an intelligent layer for AI coding that reduces LLM token consumption by up to 99%...
Tokens:554,593
Snippets:4,253
Trust Score:8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run quickstart CLI example

Source: https://github.com/yvgude/lean-ctx/blob/main/cookbook/README.md

Runs the quickstart CLI example. Requires the server to be running and dependencies installed.

```bash
cd cookbook
npm run quickstart
```

--------------------------------

### Install and start lean-ctx daemon and SDK

Source: https://github.com/yvgude/lean-ctx/blob/main/integrations/hermes-lean-ctx/README.md

Commands to install the plugin, start the lean-ctx HTTP tools API, install the Python SDK, and activate the engine in Hermes config. Note that the always-on proxy does not serve /v1/tools; use 'serve'.

```bash
# 1. Install the plugin (symlinks this checkout into ~/.hermes/plugins).
./scripts/install.sh

# 2. Start the lean-ctx HTTP tools API (serves /v1; default port 8080).
#    NOTE: the always-on proxy (port 4444+) does NOT serve /v1/tools — use serve.
lean-ctx serve --host 127.0.0.1 --port 8080

# 3. Install the SDK in Hermes' Python.
pip install lean-ctx-client

# 4. Activate the engine in ~/.hermes/config.yaml:
#    context:
#      engine: "lean-ctx"
```

--------------------------------

### Run lean-ctx install and install --repair

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/reference/01-setup-and-onboarding.md

Plain `lean-ctx install` runs the guided setup, while `install --repair` (or `--fix`) performs a non-interactive, merge-based refresh without deleting anything. Use `--repair` when you need a safe, automated fix.

```bash
lean-ctx install            # = lean-ctx setup
lean-ctx install --repair   # non-interactive repair (no deletes)
```

--------------------------------

### Install configs and start proxy (pi/forge-cli runtime)

Source: https://github.com/yvgude/lean-ctx/blob/main/_archive/bench/agent-task/r2/README.md

Commands to install the pi extension config and engine config, start the wire-level proxy on port 4444, and source the environment file. Run these in order for the pi/forge-cli runtime.

```bash
# 1. install config
mkdir -p ~/.pi/agent/extensions/pi-lean-ctx
cp bench/agent-task/r2/pi-config.json ~/.pi/agent/extensions/pi-lean-ctx/config.json
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/lean-ctx"
cp bench/agent-task/r2/lean-ctx.toml "${XDG_CONFIG_HOME:-$HOME/.config}/lean-ctx/config.toml"

# 2. start the wire-level proxy (foreground; background it for a run)
lean-ctx proxy start --port=4444 &

# 3. point the agent at the proxy
set -a; source bench/agent-task/r2/faithful-arm.env; set +a
```

--------------------------------

### Install pi-lean-ctx and initialize with Pi agent

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/guides/pi.md

Install the Pi extension via npm and initialize lean-ctx with the Pi agent. The setup command generates the AGENTS.md rules file in the project root. Verify the installation with 'lean-ctx doctor'.

```bash
# Install the Pi extension
pi install npm:pi-lean-ctx

# Or use lean-ctx's setup
lean-ctx init --agent pi

# Verify
lean-ctx doctor
```

--------------------------------

### Install cookbook dependencies

Source: https://github.com/yvgude/lean-ctx/blob/main/cookbook/README.md

Installs npm dependencies for the cookbook examples. Run from the `cookbook` directory.

```bash
cd cookbook
npm ci
```

--------------------------------

### Install lean-ctx and check status

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/ga/dr-backup-guide.md

Install lean-ctx on a fresh machine and confirm the CLI starts by checking its status.

```bash
curl -fsSL https://leanctx.com/install.sh | sh
lean-ctx status
```

--------------------------------

### Install from release artifact and onboard

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/ga/install-guide.md

After downloading the platform archive from GitHub Releases and verifying against SHA256SUMS, place the executable on PATH and run `lean-ctx onboard`.

```bash
lean-ctx onboard
```

--------------------------------

### Install and setup lean-ctx

Source: https://github.com/yvgude/lean-ctx/blob/main/rust/src/templates/SKILL.md

Install lean-ctx via curl and run setup. The command checks if lean-ctx is already installed before downloading the install script.

```bash
which lean-ctx || curl -fsSL https://raw.githubusercontent.com/yvgude/lean-ctx/main/skills/lean-ctx/scripts/install.sh | bash
lean-ctx setup
```

--------------------------------

### Build and install from source

Source: https://github.com/yvgude/lean-ctx/blob/main/_archive/vscode-extension/README.md

Commands to compile, package, and install the extension from source.

```bash
cd vscode-extension
npm install
npm run compile
npm run package
code --install-extension lean-ctx-0.1.0.vsix
```

--------------------------------

### Full control setup with lean-ctx onboard and setup

Source: https://github.com/yvgude/lean-ctx/blob/main/README.md

Alternative full-control setup: `lean-ctx onboard` connects all detected AI tools with zero prompts, while `lean-ctx setup` runs an interactive wizard with every option.

```bash
lean-ctx onboard          # connect all detected AI tools (zero prompts)
lean-ctx setup            # interactive wizard with every option
```

--------------------------------

### Setup and build commands

Source: https://github.com/yvgude/lean-ctx/blob/main/CONTRIBUTING.md

Setup commands to clone the repository, navigate to the Rust crate, build, and run tests. Requires Rust (stable), Git, and a C toolchain (cc, plus cmake for aws-lc).

```bash
git clone https://github.com/yvgude/lean-ctx.git
cd lean-ctx/rust

cargo build
cargo test
```

--------------------------------

### Use lean-ctx -c prefix for shell commands without MCP equivalents

Source: https://github.com/yvgude/lean-ctx/blob/main/rust/examples/CLAUDE.md

Prefix shell commands that lack MCP tools (git, cargo, npm) with 'lean-ctx -c' to get compressed output. The examples show the syntax for git status, cargo test, and npm install.

```bash
lean-ctx -c git status    # compressed output
lean-ctx -c cargo test    # compressed output
lean-ctx -c npm install   # compressed output
```

--------------------------------

### Quick Setup Commands

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/guides/cursor.md

Run `lean-ctx init --agent cursor` to configure MCP, rules, shell hook, and skill. Then verify with `lean-ctx doctor` and restart Cursor to load the MCP server.

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

# Verify
lean-ctx doctor

# Restart Cursor to load the MCP server
```

--------------------------------

### Usage example for LeanCtxClient

Source: https://github.com/yvgude/lean-ctx/blob/main/_archive/clients-python/README.md

Shows how to create a client, perform discovery, list tools, call a tool, and subscribe to SSE events. Requires a running server at the given URL.

```python
from leanctx import LeanCtxClient, run_conformance

client = LeanCtxClient("http://127.0.0.1:8080")

# Discovery
caps = client.capabilities()   # GET /v1/capabilities
api = client.openapi()         # GET /v1/openapi.json

# Tools
listing = client.list_tools(limit=10)
text = client.call_tool_text("ctx_read", {"path": "README.md"})

# Live events (SSE)
for event in client.subscribe_events():
    print(event["kind"], event["payload"])
```

--------------------------------

### Start LeanCTX HTTP server

Source: https://github.com/yvgude/lean-ctx/blob/main/cookbook/README.md

Starts the LeanCTX HTTP server on 127.0.0.1:8080 with a specified project root. Required before running any examples.

```bash
lean-ctx serve --host 127.0.0.1 --port 8080 --project-root /path/to/project
```

--------------------------------

### Quick Setup: lean-ctx init --agent opencode

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/guides/opencode.md

Run this to configure OpenCode with lean-ctx. It sets up MCP, rules, and shell hook. Then verify with `lean-ctx doctor`.

```bash
# One command — configures MCP, rules, and shell hook
lean-ctx init --agent opencode

# Verify
lean-ctx doctor
```

--------------------------------

### Initialize and validate configuration

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/ga/admin-guide.md

Create a starter configuration file and validate every change before applying it. Use `lean-ctx config set <key> <value>` for a single audited change, and `lean-ctx restart` for changes read by a running process.

```bash
lean-ctx config init
lean-ctx config validate
lean-ctx config apply
```

--------------------------------

### Set up scrape token and start dashboard

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/integrations/datadog.md

Creates a read-only scrape token and starts the dashboard on port 3333. The token is accepted only for GET /metrics and never grants dashboard or API access.

```bash
export LEAN_CTX_SCRAPE_TOKEN="$(openssl rand -hex 24)"
lean-ctx dashboard --port 3333   # or your existing dashboard/daemon setup
```

--------------------------------

### Automated setup with lean-ctx init

Source: https://github.com/yvgude/lean-ctx/blob/main/packages/pi-lean-ctx/README.md

Use the automated setup command to initialize the agent for Pi.

```bash
lean-ctx init --agent pi
```

--------------------------------

### Run diagnostic and configuration commands

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/ga/admin-guide.md

Start with these commands to check the installation and view the effective configuration. `lean-ctx config schema` is authoritative for the installed release and avoids copying keys from an older config format.

```bash
lean-ctx doctor
lean-ctx config show
lean-ctx config schema
```

--------------------------------

### Top-level lifecycle commands

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/ga/admin-guide.md

Use the top-level lifecycle commands for the installed local service set. Some runbooks abbreviate the first action as `lean-ctx start`, but use the explicit component start commands on current releases.

```bash
lean-ctx stop
lean-ctx restart
```

--------------------------------

### Session Start: Project Orientation

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/guides/opencode.md

At the start of a session, use these commands to quickly orient: overview for task description, tree for structure, and map reads for key files.

```bash
# 1. Fast project orientation
ctx_overview("your task description")

# 2. Understand project structure
ctx_tree("src/", 3)

# 3. Read key files in map mode
ctx_read("src/lib.rs", "map")
ctx_read("src/main.rs", "map")
```

--------------------------------

### Fix OpenCode not finding lean-ctx binary

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/guides/opencode.md

Check if lean-ctx is in PATH, add the appropriate directory for cargo or npm installations, and re-run setup.

```bash
# Check PATH
which lean-ctx

# If installed via cargo
export PATH="$HOME/.cargo/bin:$PATH"

# If installed via npm
export PATH="$HOME/.npm-global/bin:$PATH"

# Then re-setup
lean-ctx init --agent opencode
```

--------------------------------

### Install lean-ctx via curl, brew, npm, or cargo

Source: https://github.com/yvgude/lean-ctx/blob/main/_archive/discord-faq/01-installation-setup.md

Provides four installation commands for lean-ctx: universal curl script, Homebrew tap, npm global package, and Cargo. The curl method does not require Rust; the script auto-detects missing cargo and downloads a pre-built binary since v3.2.3. After installation, run `lean-ctx setup` and `lean-ctx doctor` to verify.

```bash
curl -fsSL https://leanctx.com/install.sh | sh   # universal, no Rust needed
brew tap yvgude/lean-ctx && brew install lean-ctx  # macOS / Linux
npm install -g lean-ctx-bin                        # Node.js
cargo install lean-ctx                             # Rust
```

--------------------------------

### Team and CI: serve with config and bootstrap

Source: https://github.com/yvgude/lean-ctx/blob/main/README.md

Serve a team configuration and bootstrap for zero-prompt CI setup.

```bash
lean-ctx team serve --config team.toml
lean-ctx bootstrap            # zero-prompt CI setup
```

--------------------------------

### lean-ctx gain dashboard output example

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/reference/02-daily-use.md

Example output of the lean-ctx gain command showing a populated token savings dashboard with real numbers from a long-running install. Includes tokens saved, compression percentage, commands count, USD saved, cost breakdown, and a mascot level-up indicator.

```text
  ╭──────────────────────────────────────────────────────────────╮
  │    ◆  lean-ctx   Token Savings Dashboard                     │
  ├──────────────────────────────────────────────────────────────┤
  │    388.8M        62.6%         18,707        $983.19         │
  │    tokens saved  compression   commands      USD saved       │
  ╰──────────────────────────────────────────────────────────────╯
    past 30 days:  $971.96 saved

  Cost Breakdown  @ $2.50/M input · $10.00/M output
  ──────────────────────────────────────────────────────────────
    Without lean-ctx     $1585.68   $1552.01 input + $33.67 output
    With lean-ctx         $602.50   $580.05 input + $22.45 output
    You saved             $983.19   input $971.96 + output $11.22
```

--------------------------------

### Example .lean-ctx/ctxpkg.lock TOML entry

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/contracts/ctxpkg-registry-v1.md

Shows the structure of a lockfile entry recording a remote install, including package name, version, artifact SHA-256, and registry URL.

```toml
[[package]]
name = "@acme/auth-context"
version = "1.2.0"
artifact_sha256 = "…"
registry = "https://ctxpkg.com/api"
```
Tokens:
Raw