### Install and Setup lean-ctx

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

Installs lean-ctx if not already present and then runs the setup command. This is the initial step before using the tool's functionalities.

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

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

### Install lean-ctx with Various Package Managers

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

Use these commands to install lean-ctx depending on your operating system and preferred package manager. 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
```

```bash
brew tap yvgude/lean-ctx && brew install lean-ctx  # macOS / Linux
```

```bash
npm install -g lean-ctx-bin                        # Node.js
```

```bash
cargo install lean-ctx                             # Rust
```

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

### Automated Setup for pi-lean-ctx

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

Initiates the setup process for pi-lean-ctx, configuring it as a Pi agent. This command may handle installation and configuration steps automatically.

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

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

### Start Lean-ctx MCP Server

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

Start the MCP server for editors using standard input/output.

```bash
lean-ctx                       # Start MCP server (stdio) — used by editors
```

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

### Docker Setup for Lean-ctx

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Configure a Dockerfile for lean-ctx integration. This includes non-interactive setup, exposing ports, and starting the lean-ctx server with your application.

```dockerfile
RUN lean-ctx setup --yes

EXPOSE 8080

CMD lean-ctx serve --host 0.0.0.0 --port 8080 --project-root /workspace &
```

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

### Install lean-ctx and pi-lean-ctx Package

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

Installs the `lean-ctx` binary using Cargo or Homebrew, then installs the `pi-lean-ctx` package for the Pi agent. A restart of Pi is required after installation.

```bash
# 1. Install lean-ctx (if not already installed)
# or: brew tap yvgude/lean-ctx && brew install lean-ctx

# 2. Install the Pi package
pi install npm:pi-lean-ctx

# 3. Restart Pi
```

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

### Docker Setup for LeanCtx

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Instructions for setting up and running LeanCtx within a Docker container, including installing the binary and configuring environment variables for tools like Claude Code.

```APIDOC
## Docker Setup

### Description
This section guides you through setting up LeanCtx to run inside a Docker container. It covers installing the pre-built binary and configuring necessary environment variables, particularly for integration with AI coding assistants like Claude Code.

### Dockerfile Example
An example Dockerfile demonstrating how to install LeanCtx and set up environment variables.

```dockerfile
FROM ubuntu:24.04

# Install lean-ctx (pre-built binary, no Rust needed)
RUN curl -fsSL https://leanctx.com/install.sh | sh

# For Claude Code: env file sourced before every command
ENV CLAUDE_ENV_FILE=/root/.config/lean-ctx/env.sh
```
```

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

### Install Lean-ctx in WSL Ubuntu

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/integrations/windows10-opencode-wsl-setup.md

Installs the Lean-ctx binary using a curl script. Ensure you have WSL Ubuntu installed.

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

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

### Install LeanCTX

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

Verify lean-ctx installation or run the installation script. This is a prerequisite before using lean-ctx.

```bash
which lean-ctx || bash scripts/install.sh
```

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

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

### Universal Installer Script

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

Use this command to download and execute the universal installer script for lean-ctx. This method does not require a Rust toolchain.

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

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

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

### Install lean-ctx

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

Provides multiple installation methods for lean-ctx. Choose the one that best suits your environment.

```bash
curl -fsSL https://leanctx.com/install.sh | sh      # universal (no Rust needed)
```

```bash
brew tap yvgude/lean-ctx && brew install lean-ctx    # macOS / Linux
```

```bash
npm install -g lean-ctx-bin                          # Node.js
```

```bash
cargo install lean-ctx                               # Rust
```

```bash
pi install npm:pi-lean-ctx                           # Pi Coding Agent
```

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

### Docker Setup for LeanCtx

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Dockerfile to set up a Docker container with LeanCtx installed. It installs the pre-built binary, avoiding the need for Rust compilation.

```dockerfile
FROM ubuntu:24.04

# Install lean-ctx (pre-built binary, no Rust needed)
RUN curl -fsSL https://leanctx.com/install.sh | sh

# For Claude Code: env file sourced before every command
ENV CLAUDE_ENV_FILE=/root/.config/lean-ctx/env.sh
```

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

### Run Lean-ctx Commands

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Execute various lean-ctx commands for summaries, benchmarking, and safety levels. No specific setup is required beyond having lean-ctx installed.

```bash
lean-ctx gain --web
```

```bash
lean-ctx wrapped --week
```

```bash
lean-ctx wrapped --month
```

```bash
lean-ctx benchmark report .
```

```bash
lean-ctx safety-levels
```

```bash
lean-ctx ghost
```

```bash
lean-ctx ghost --json
```

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

### Setup Cookbook/SDK Environment

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

Commands to set up the Node.js environment for the cookbook and packages. Requires Node.js (>= 22.12.0) and npm.

```bash
cd cookbook
npm ci
npm test
```

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

### Install lean-ctx using cargo-binstall

Source: https://github.com/yvgude/lean-ctx/blob/main/discord-faq/08-windows.md

Use this command to quickly install or update lean-ctx with prebuilt binaries. This is the preferred method for speed.

```bash
cargo binstall lean-ctx
```

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

### Install Native Messaging Host

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

Steps to install the native messaging host for full compression. Requires navigating to the native-host directory, setting execute permissions, and running the install script. Ensure your Extension ID is correctly configured in the manifest.

```bash
cd native-host
chmod +x install.sh bridge.sh
./install.sh
```

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

### Install lean-ctx

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Install lean-ctx using various package managers. No Rust toolchain is required for the universal binary.

```bash
# Universal (pre-built binary, no Rust needed)
curl -fsSL https://leanctx.com/install.sh | sh
```

```bash
# macOS / Linux via Homebrew
brew tap yvgude/lean-ctx && brew install lean-ctx
```

```bash
# Node.js
npm install -g lean-ctx-bin
```

```bash
# Rust / crates.io
cargo install lean-ctx
```

```bash
# Pi Coding Agent
pi install npm:pi-lean-ctx
```

```bash
# Verify and connect to your AI tool
lean-ctx setup    # auto-detects installed editors; installs MCP + shell hooks
lean-ctx doctor   # diagnose hook + MCP configuration
```

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

### Install lean-ctx with Homebrew

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

Install lean-ctx using Homebrew on macOS or Linux. This command taps the repository and installs the package.

```bash
brew tap yvgude/lean-ctx
brew install lean-ctx
```

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

### Verify lean-ctx Installation

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

Verify that lean-ctx has been installed correctly by checking its version and running a basic command to see token savings statistics.

```bash
lean-ctx --version   # Should show "lean-ctx 3.6.0"
lean-ctx gain        # Should show token savings stats
```

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

### Install lean-ctx with Homebrew

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

Install lean-ctx on macOS or Linux using Homebrew. This requires adding the custom tap first.

```bash
brew tap yvgude/lean-ctx && brew install lean-ctx
```

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

### Install lean-ctx on Arch Linux (AUR)

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

Install lean-ctx from the Arch User Repository (AUR). Choose between building from source or using a pre-built binary.

```bash
yay -S lean-ctx        # builds from source (crates.io)
# or
yay -S lean-ctx-bin    # pre-built binary (GitHub Releases)
```

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

### Copy Lean-CTX Rule for Cursor

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

Copy this example rule file to `.cursor/rules/lean-ctx.mdc` in your project for maximum token savings with Cursor.

```bash
cp rust/examples/lean-ctx.mdc .cursor/rules/lean-ctx.mdc
```

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

### Install lean-ctx-bin Globally

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

Install the lean-ctx-bin package globally using npm. This makes the lean-ctx command available in your terminal.

```bash
npm install -g lean-ctx-bin
```

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

### Verify Lean-ctx Installation

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/integrations/windows10-opencode-wsl-setup.md

Checks if the lean-ctx command is accessible and displays its version. Expected output indicates a successful installation.

```bash
lean-ctx --version
```

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

### Lean-ctx Core Commands

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

Examples of core lean-ctx commands for managing context, including live updates and weekly summaries.

```bash
lean-ctx gain --live
```

```bash
lean-ctx wrapped --week
```

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

### Install lean-ctx in Docker

Source: https://github.com/yvgude/lean-ctx/blob/main/discord-faq/07-docker-remote.md

Installs the lean-ctx binary within a Docker image and sets up the environment file for Claude Code. Ensure CLAUDE_ENV_FILE is used for Claude Code in Docker.

```dockerfile
# Download pre-built binary
RUN curl -fsSL https://leanctx.com/install.sh | sh

# For Claude Code: set env file
ENV CLAUDE_ENV_FILE=/root/.lean-ctx/env
RUN lean-ctx setup
```

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

### Initialize Lean-CTX Agent for Codex

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

Run this command after configuring Codex to install necessary hooks and documentation for Lean-CTX integration.

```bash
lean-ctx init --agent codex
```

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

### Diagnose and Fix Lean Context Issues

Source: https://github.com/yvgude/lean-ctx/blob/main/discord-faq/09-troubleshooting.md

Run these commands to diagnose problems, disable the tool, or re-run setup.

```bash
lean-ctx doctor            # diagnose everything
```

```bash
lean-ctx-off               # disable immediately (current session)
```

```bash
lean-ctx setup             # re-run setup to fix hooks
```

```bash
lean-ctx update            # get latest fixes
```

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

### Generate Lean-ctx Benchmark Report

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

Use this command to generate a benchmark report for your project. Ensure lean-ctx is installed and accessible in your PATH.

```bash
lean-ctx benchmark report .
```

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

### Build and Verify lean-ctx from Source

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

Clone the repository, build the release binary, and compare its version with the installed version to ensure build reproducibility. This helps verify that the binary matches the source code.

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

lean-ctx --version
./target/release/lean-ctx --version
```

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

### Build Website for Contract Versioning Docs

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

Build the website for contract versioning documentation. This command is run from the 'worktrees/deploy-ctxos/website' directory.

```bash
cd worktrees/deploy-ctxos/website && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm run -s build
```

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

### CLI - Initial Setup and Agent Init

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Set up lean-ctx by auto-detecting AI agents or initializing for a specific agent. Global shell hooks can also be applied.

```bash
# Auto-detect all installed AI tools and set up everything
lean-ctx setup
```

```bash
# Initialize for a specific agent only
lean-ctx init --agent cursor
lean-ctx init --agent claude
lean-ctx init --agent codex
lean-ctx init --agent gemini
lean-ctx init --agent windsurf
lean-ctx init --agent copilot
lean-ctx init --agent opencode
lean-ctx init --agent kiro
lean-ctx init --agent zed           # MCP-only (no shell hooks)
lean-ctx init --agent jetbrains     # MCP-only
```

```bash
# Global shell hooks (all shells: bash, zsh, fish, PowerShell)
lean-ctx init --global
```

```bash
# Verify setup
lean-ctx doctor
lean-ctx doctor --json              # machine-readable report for bug reports
```

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

### Get WSL Distro Name

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/integrations/windows10-opencode-wsl-setup.md

Retrieves the name of the installed WSL distribution, typically 'Ubuntu'.

```powershell
wsl -l -v
```

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

### Generate Project Overview with ctx_overview

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Initializes the session and generates a compact project overview including top knowledge facts, architectural hotspots, and graph connectivity. Call at the start of each session.

```rust
ctx_overview(task="Implement rate limiting middleware")
```

```rust
ctx_overview(task="Fix authentication bug in login flow")
```

```rust
# general project overview
ctx_overview()
```

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

### LeanCtxClient Initialization and Basic Usage

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Demonstrates how to initialize the LeanCtxClient with configuration options and provides examples for common operations like health checks, listing tools, and calling tools for raw or text results.

```APIDOC
## LeanCtxClient Initialization and Basic Usage

### Description
Initialize the `LeanCtxClient` with your desired configuration, such as the base URL, authentication token, workspace ID, and channel ID. The SDK provides methods for interacting with various LeanCtx features.

### Initialization
```typescript
import { LeanCtxClient, LeanCtxHttpError } from "@leanctx/sdk";

const client = new LeanCtxClient({
  baseUrl: process.env.LEANCTX_BASE_URL ?? "http://127.0.0.1:8080",
  bearerToken: process.env.LEANCTX_BEARER_TOKEN,  // optional
  workspaceId: "my-workspace",                     // optional, per-request override also supported
  channelId: "main",
});
```

### Methods

#### Health Check
Checks the health status of the LeanCtx service.

```typescript
const status = await client.health();
console.log(status); // "ok"
```

#### List Tools
Retrieves a list of available tools with pagination.

```typescript
const tools = await client.listTools({ offset: 0, limit: 20 });
console.log(`${tools.tools.length}/${tools.total} tools`);
```

#### Call Tool Result (Raw)
Calls a specified tool and returns the raw result.

```typescript
const raw = await client.callToolResult("ctx_read", {
  path: "src/main.rs",
  mode: "map",
});
```

#### Call Tool Text (Common)
Calls a specified tool and returns the result as formatted text. This is the most common way to interact with tools.

```typescript
const text = await client.callToolText("ctx_read", {
  path: "README.md",
  mode: "lines:1-40",
});
console.log(text);
```

### Error Handling
Handles potential HTTP errors during client operations.

```typescript
try {
  await client.callToolText("ctx_read", { path: "/etc/passwd" });
} catch (e) {
  if (e instanceof LeanCtxHttpError) {
    console.error(`HTTP ${e.status} ${e.method} ${e.url}: ${e.message}`);
    console.error("error_code:", e.errorCode);
  }
}
```
```

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

### Create and Manage Lean-ctx Context Packages

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Bundle project knowledge, graph, session, and gotchas into portable `.lctxpkg` files. Supports creation, listing, info, export, import, installation, and removal of packages.

```bash
lean-ctx pack create --name "my-project-v1" --description "Initial context snapshot"
```

```bash
lean-ctx pack list
```

```bash
lean-ctx pack info my-project-v1
```

```bash
lean-ctx pack export my-project-v1 --output ./my-project-v1.lctxpkg
```

```bash
lean-ctx pack import ./my-project-v1.lctxpkg
```

```bash
lean-ctx pack install my-project-v1
```

```bash
lean-ctx pack auto-load my-project-v1 --enable
```

```bash
lean-ctx pack remove my-project-v1
```

```bash
lean-ctx pack --pr
```

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

### Install lean-ctx with Cargo

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

Install lean-ctx using Cargo, the Rust package manager. This method requires a Rust toolchain to be installed.

```bash
cargo install lean-ctx
```

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

### Manage Session State with ctx_session

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Manages session state including task tracking, structured recovery snapshots, terse mode, and role/budget controls. Use 'task' to set a task, 'update' to record findings, 'snapshot' to save, 'restore' to recover, 'resume' to get resume info, 'reset' to start fresh, 'configure' for settings, 'budget' to check limits, and 'role' to manage agent roles.

```rust
ctx_session(action="task", value="Implement OAuth2 PKCE flow")
```

```rust
ctx_session(action="update", findings="Found token refresh logic in auth/refresh.rs")
```

```rust
# save compaction-safe recovery snapshot
ctx_session(action="snapshot")
```

```rust
# restore from latest snapshot after compaction
ctx_session(action="restore")
```

```rust
# get compact session resume block
ctx_session(action="resume")
```

```rust
# start fresh session
ctx_session(action="reset")
```

```rust
# enable concise response mode
ctx_session(action="configure", terse=true)
```

```rust
# check current token/cost budget
ctx_session(action="budget")
```

```rust
# list/switch agent role
ctx_session(action="role")
```

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

### Start Live Data Polling

Source: https://github.com/yvgude/lean-ctx/blob/main/rust/src/dashboard/dashboard.html

Starts interval-based polling to load live data at a regular interval (2 seconds). Clears any existing live polling interval before starting a new one.

```javascript
function startLivePolling() { if (liveInterval) clearInterval(liveInterval); liveInterval = setInterval(loadLive, 2000); }
```

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

### Verify lean-ctx installation

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

Runs a diagnostic check to ensure lean-ctx is installed and configured correctly.

```bash
lean-ctx doctor
```

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

### Lean-ctx Version and Help

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

Display the current version of lean-ctx or access the full help documentation.

```bash
lean-ctx --version             # Show version
```

```bash
lean-ctx --help                # Full help
```

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

### Redaction Example: Refs Only (Default)

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/contracts/http-mcp-contract-v1.md

Example of an event payload redacted to expose only references. This is the default redaction level.

```json
{
  "tool": "ctx_read",
  "kind": "tool_call_recorded",
  "workspace_id": "ws1",
  "redacted": true
}
```

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

### Manage Context Packages

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

Commands for creating, listing, inspecting, exporting, importing, installing, auto-loading, and removing context packages. Includes an option for PR context packs.

```bash
lean-ctx pack create --name my-pkg          # Bundle Knowledge + Graph + Session + Gotchas
```

```bash
lean-ctx pack list                          # List installed packages
```

```bash
lean-ctx pack info my-pkg                   # Detailed view (stats, integrity, provenance)
```

```bash
lean-ctx pack export my-pkg -o my.lctxpkg   # Export to portable .lctxpkg file
```

```bash
lean-ctx pack import my.lctxpkg --apply     # Import and apply to current project
```

```bash
lean-ctx pack install my-pkg                # Apply package (merge knowledge, import graph)
```

```bash
lean-ctx pack auto-load my-pkg              # Auto-load on ctx_overview session start
```

```bash
lean-ctx pack remove my-pkg                 # Remove from local registry
```

```bash
lean-ctx pack --pr                          # PR context pack (unchanged)
```

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

### Start Lean-ctx HTTP Server

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Launch lean-ctx as a Streamable HTTP MCP server. Supports configuration of host, port, project root, and authentication tokens. Can run in daemon mode.

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

```bash
lean-ctx serve --host 127.0.0.1 --port 8080 \
  --project-root /path/to/project \
  --auth-token "my-secret-token"
```

```bash
lean-ctx serve --host 0.0.0.0 --port 8080 --project-root /workspace
```

```bash
lean-ctx serve --daemon
```

```bash
lean-ctx serve --status
```

```bash
lean-ctx serve --stop
```

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

### macOS Autoupdate Installation

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

Installs the autoupdate script and generates a launchd plist file to schedule it. Ensure paths in the plist are correct for your system.

```bash
cp autoupdate.sh ~/.lean-ctx/autoupdate.sh
chmod +x ~/.lean-ctx/autoupdate.sh

# generate plist with your actual paths and register it
SCRIPT="$HOME/.lean-ctx/autoupdate.sh"
PLIST="$HOME/Library/LaunchAgents/com.leactx.autoupdate.plist"
cat > "$PLIST" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>com.leactx.autoupdate</string>
  <key>ProgramArguments</key>
  <array><string>/bin/bash</string><string>$SCRIPT</string></array>
  <key>StartInterval</key><integer>21600</integer>
  <key>RunAtLoad</key><false/>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    <key>HOME</key><string>$HOME</string>
  </dict>
  <key>StandardOutPath</key><string>$HOME/.lean-ctx/autoupdate-stdout.log</string>
  <key>StandardErrorPath</key><string>$HOME/.lean-ctx/autoupdate-stderr.log</string>
</dict></plist>
EOF
launchctl load "$PLIST"
```

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

### Redaction Example: Full

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/contracts/http-mcp-contract-v1.md

Example of an event payload with full redaction, exposing the complete payload without any redaction. Requires 'Audit' scope.

```json
{
  "tool": "ctx_read",
  "kind": "tool_call_recorded",
  "workspace_id": "ws1",
  "content": "use std::sync::Arc;\n...",
  "arguments": { "path": "src/main.rs", "mode": "full" }
}
```

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

### Lean-ctx Demo Commands

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

Demonstration commands for various lean-ctx functionalities, including reading files, executing shell commands, and managing context.

```bash
lean-ctx read rust/src/server/mod.rs -m map
```

```bash
lean-ctx -c "git log -n 5 --oneline"
```

```bash
lean-ctx gain --live
```

```bash
lean-ctx dashboard                              # Context Manager (browser)
```

```bash
lean-ctx watch                                  # TUI monitor
```

```bash
lean-ctx benchmark report .
```

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

### Initialize lean-ctx with pi-mcp-adapter Integration

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

Initializes lean-ctx, allowing it to integrate with `pi-mcp-adapter`. This can be done automatically by `lean-ctx init --agent pi` or through manual configuration in `~/.pi/agent/mcp.json`.

```bash
# Option A: lean-ctx writes the config for you
lean-ctx init --agent pi

# Option B: Manual configuration in ~/.pi/agent/mcp.json
```

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

### Redaction Example: Summary

Source: https://github.com/yvgude/lean-ctx/blob/main/docs/contracts/http-mcp-contract-v1.md

Example of an event payload redacted to the summary level. Sensitive content fields are replaced with '[redacted]', but metadata is preserved.

```json
{
  "tool": "ctx_read",
  "kind": "tool_call_recorded",
  "workspace_id": "ws1",
  "content": "[redacted]",
  "arguments": "[redacted]"
}
```

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

### Initialize LeanCtxClient and make calls

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Instantiate the LeanCtxClient with configuration and demonstrate various API calls including health checks, listing tools, calling tools for raw or text output, knowledge management, and subscribing to events. Includes error handling for HTTP errors.

```typescript
import { LeanCtxClient, LeanCtxHttpError } from "@leanctx/sdk";

const client = new LeanCtxClient({
  baseUrl: process.env.LEANCTX_BASE_URL ?? "http://127.0.0.1:8080",
  bearerToken: process.env.LEANCTX_BEARER_TOKEN,  // optional
  workspaceId: "my-workspace",                     // optional, per-request override also supported
  channelId: "main",
});

// --- Health check ---
const status = await client.health();
console.log(status); // "ok"

// --- List tools ---
const tools = await client.listTools({ offset: 0, limit: 20 });
console.log(`${tools.tools.length}/${tools.total} tools`);

// --- Call a tool and get raw result ---
const raw = await client.callToolResult("ctx_read", {
  path: "src/main.rs",
  mode: "map",
});

// --- Call a tool and get text output (most common) ---
const text = await client.callToolText("ctx_read", {
  path: "README.md",
  mode: "lines:1-40",
});
console.log(text);

// --- Knowledge: remember + recall ---
await client.callToolText("ctx_knowledge", {
  action: "remember",
  category: "architecture",
  key: "http_framework",
  value: "Axum 0.8; routes in src/http_server/mod.rs",
});

const facts = await client.callToolText("ctx_knowledge", {
  action: "recall",
  category: "architecture",
});
console.log(facts);

// --- Knowledge: relate + diagram ---
await client.callToolText("ctx_knowledge", {
  action: "relate",
  category: "architecture",
  key: "http_framework",
  value: "depends_on",
  query: "architecture/db_driver",
});

const diagram = await client.callToolText("ctx_knowledge", {
  action: "relations_diagram",
  category: "architecture",
  key: "http_framework",
  query: "all",
});
console.log(diagram); // Mermaid graph definition

// --- Subscribe to context events (SSE) ---
for await (const event of client.subscribeEvents({ workspaceId: "my-ws" })) {
  console.log(event.kind, event.payload);
  // event.kind: "ToolCall" | "CacheHit" | "Compression" | "KnowledgeUpdate" | ...
}

// --- Error handling ---
try {
  await client.callToolText("ctx_read", { path: "/etc/passwd" });
} catch (e) {
  if (e instanceof LeanCtxHttpError) {
    console.error(`HTTP ${e.status} ${e.method} ${e.url}: ${e.message}`);
    console.error("error_code:", e.errorCode);
  }
}
```

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

### Install Lean-ctx Without Tree-sitter

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

Install lean-ctx with a smaller binary size by excluding the tree-sitter default features. This is useful if AST-based parsing is not required.

```bash
cargo install lean-ctx --no-default-features
```

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

### Install OpenClaw Shell Hook and Skill

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

Install Lean-CTX shell aliases globally and optionally copy the Lean-CTX skill for deeper integration with OpenClaw.

```bash
# 1. Install shell aliases (if not done already)
lean-ctx init --global
source ~/.zshrc

# 2. (Optional) Install the LeanCTX skill for deeper integration
mkdir -p ~/.openclaw/skills/lean-ctx
cp skills/lean-ctx/SKILL.md ~/.openclaw/skills/lean-ctx/

```

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

### Linux Autoupdate Installation

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

Installs the autoupdate script and configures a cron job to run it every 6 hours. Ensure the script path is correct.

```bash
cp autoupdate.sh ~/.lean-ctx/autoupdate.sh
chmod +x ~/.lean-ctx/autoupdate.sh
(crontab -l 2>/dev/null; echo "0 */6 * * * bash $HOME/.lean-ctx/autoupdate.sh") | crontab -
```

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

### Manage context packages with ctx_pack

Source: https://context7.com/yvgude/lean-ctx/llms.txt

Build and manage context packages. Actions include creating a package with a name and description, listing existing packages, installing a package by name, or creating a PR-focused context pack.

```python
ctx_pack(action="create", name="sprint-42", description="Sprint 42 context")
```

```python
ctx_pack(action="list")
```

```python
ctx_pack(action="install", name="sprint-42")
```

```python
ctx_pack(action="pr")              # build PR-focused context pack
```

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

### Using Lean-ctx MCP Tools

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

Replace built-in tools with Lean-ctx MCP equivalents for optimized token usage. Supported operations include reading files, shell commands, code search, and directory listing.

```text
ctx_read(path, mode)
```

```text
ctx_shell(command)
```

```text
ctx_search(pattern, path)
```

```text
ctx_tree(path, depth)
```