/lean-ctx

name: lean-ctx
description: Local context tooling for AI agents. Use it to select, shape, reuse, recover, and inspect context before inference when reading files, running shell commands, searching code, or exploring directories.

LeanCTX — Local Context SDK for AI Agents

LeanCTX is a local context layer for existing agents. It provides selectable file representations, focused search, controlled shell-output shaping, session continuity, and recovery to exact source when needed.

Setup (run first)

Before using lean-ctx, verify it is installed:

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

If the install script is not available locally, install manually:

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

After installation, run the one-command setup (installs shell hook + editor wiring + rules + skills):

lean-ctx setup

lean-ctx supports two integration styles (auto-detected per agent):

• **Hybrid (default where shell access exists)**: MCP for cached reads/search + shell hooks that compress command output.
• **MCP (for IDE-extension agents without reliable shell hooks)**: cached reads + all tools via MCP.

When to use lean-ctx

Prefer the current shell's configured compression over nested wrappers. In agent shells, run commands normally unless the user explicitly asks for `lean-ctx -c <command>` or task setup/docs explicitly say the shell is not wrapped. Do not inspect env vars just to decide; users may forbid env access.

Use `lean-ctx -c <command>` over running commands directly only when:

• The command produces verbose output (build logs, git diffs, dependency trees, test results)
• You are reading files and only need the structure or API surface
• You want to inspect local context-usage estimates for the current session

Shell commands

git status                      # Compressed by configured agent shell/wrapper
git diff                        # Meaningful diff lines when configured
git log --oneline -10
npm install                     # Strips progress bars/noise when configured
cargo build
cargo test
docker ps
kubectl get pods
aws ec2 describe-instances
helm list
prisma migrate dev
curl -s <url>                   # JSON schema extraction
ls -la <dir>                    # Grouped directory listing

# Explicit user request / documented unwrapped shell:
lean-ctx -c "git status"

Supported: git, npm, pnpm, yarn, bun, deno, cargo, docker, kubectl, helm, gh, pip, ruff, go, eslint, prettier, tsc, aws, psql, mysql, prisma, swift, zig, cmake, ansible, composer, mix, bazel, systemd, terraform, make, maven, dotnet, flutter, poetry, rubocop, playwright, curl, wget, and more.

File reading (compressed modes)

lean-ctx read <file>                    # Full content with structured header
lean-ctx read <file> -m map             # Dependency graph + exports + API (~5-15% tokens)
lean-ctx read <file> -m signatures      # Function/class signatures only (~10-20% tokens)
lean-ctx read <file> -m aggressive      # Syntax-stripped (~30-50% tokens)
lean-ctx read <file> -m entropy         # Shannon entropy filtered (~20-40% tokens)
lean-ctx read <file> -m diff            # Only changed lines since last read

Use `map` mode when you need to understand what a file does without reading every line. Use `signatures` mode when you need the API surface of a module (tree-sitter for 26 languages). Use `anchored` mode (MCP: `ctx_read(mode="anchored")`) when you will edit the file — it adds `N:hh|` anchors so `ctx_patch` can edit by reference without echoing old text.

AI Tool Integration

lean-ctx init --global                # Install shell aliases
lean-ctx init --agent cursor          # Hybrid (MCP reads/search + shell hooks)
lean-ctx init --agent claude          # Hybrid (Claude Code)
lean-ctx init --agent codebuddy       # Hybrid (CodeBuddy)
lean-ctx init --agent codex           # Hybrid (Codex CLI)
lean-ctx init --agent opencode        # Hybrid (OpenCode)

lean-ctx init --agent copilot         # MCP (VS Code / Copilot)
lean-ctx init --agent jetbrains       # MCP (JetBrains)
lean-ctx init --agent windsurf        # Hybrid (Windsurf)

# Mode is auto-detected; override with --mode mcp|hybrid if needed.

Local knowledge and session continuity

CLI (works in Hybrid and MCP setups):

lean-ctx knowledge remember "value" --category <c> --key <k>
lean-ctx knowledge recall "query"
lean-ctx knowledge search "query"
lean-ctx knowledge export [--format json|jsonl|simple] [--output <path>]
lean-ctx knowledge import <path> [--merge replace|append|skip-existing] [--dry-run]
lean-ctx knowledge remove --category <c> --key <k>
lean-ctx knowledge consolidate [--all]

lean-ctx session task "what you're doing"
lean-ctx session finding "what you found"
lean-ctx session decision "what you decided"
lean-ctx session save

If MCP is enabled for your IDE, the same local capabilities are also available as MCP tools (`ctx_knowledge`, `ctx_session`, ...). Experimental local collaboration tools are opt-in and not part of the default public Runtime surface.

Additional Intelligence Tools

• `ctx_patch(path, ops)` — anchored editing: `N:hh|` line+hash anchors from `ctx_read(mode="anchored")`, batch-atomic, `op=create` for new files (`ctx_edit` is the legacy str-replace fallback)
• `ctx_overview(task)` — task-relevant project map at session start
• `ctx_preload(task)` — proactive context loader, caches task-relevant files
• `ctx_semantic_search(query)` — BM25 code search by meaning across the project
• `ctx_intent` now supports multi-intent detection and complexity classification
• Semantic cache: TF-IDF + cosine similarity for finding similar files across reads

Session continuity

lean-ctx sessions list          # List all CCP sessions
lean-ctx sessions show          # Show latest session state
lean-ctx sessions delete <id>   # Delete one saved session
lean-ctx wr