lean-ctx — Claude Code rule: what it does and how to install
This rule steers the agent toward lean-ctx MCP tools for file reads, search, and shell commands. It fits tasks where cached, compact context matters.
Apache-2.0 ★ 3,956 updated 2026-11-13
.claude/rules/lean-ctx.mdWhat lean-ctx does
The rule sets tool preferences for working with project context: use mcp_lean_ctx_ctx_read for file reads, mcp_lean_ctx_ctx_multi_read for batches, mcp_lean_ctx_ctx_search for search, mcp_lean_ctx_ctx_tree for directory maps, and mcp_lean_ctx_ctx_shell for commands. For large files, it recommends starting with signatures or a map. Long tasks can preload the cache and checkpoint context with compression.
Kiro’s native tools remain the choice for writing or appending files, exact string replacement, diagnostics, and deletion. The lean-ctx MCP server must be installed in the workspace for its tools to be available. If an edit fails, the rule says to switch straight to mcp_lean_ctx_ctx_edit rather than retrying the same approach.
For Claude Code, place the rule at .claude/rules/lean-ctx.md. Cline uses .clinerules/lean-ctx.md.
What it helps with
- reuse cached file reads
- search project files with
.gitignoreawareness - compress test and shell output
- inspect directory maps with file counts
- carry useful findings into later sessions
Example prompts for the agent
- Find calls to
createUserand return compact search results. - For this large file, show its structure map before locating the error handler.
- Run the tests and give me the compressed command output.
How to install lean-ctx
Manually: put the files in place
.claude/rules/lean-ctx.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/lean-ctx.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/lean-ctx.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/lean-ctx.mdManually: put the files in place
.clinerules/lean-ctx.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about lean-ctx
How do I install lean-ctx in Claude Code?
Place the rule file at .claude/rules/lean-ctx.md.
What does lean-ctx do?
The rule tells the agent to favor lean-ctx MCP tools for reading, searching, and shell commands. It keeps native Kiro tools for selected editing and IDE operations.
Which operations should use native Kiro tools?
Use native tools for file writes and appends, exact replacements, renames, relocation, diagnostics, and file deletion.
Source text
lean-ctx.md · Apache-2.0
---
inclusion: always
---
# LeanCTX — Context Gateway for AI agents
The workspace has the `lean-ctx` MCP server installed. You MUST prefer lean-ctx tools over native equivalents for token efficiency and caching.
## Mandatory Tool Preferences
| Use this | Instead of | Why |
|----------|-----------|-----|
| `mcp_lean_ctx_ctx_read` | `readFile`, `readCode` | Cached reads, 10 compression modes, re-reads cost ~13 tokens |
| `mcp_lean_ctx_ctx_multi_read` | `readMultipleFiles` | Batch cached reads in one call |
| `mcp_lean_ctx_ctx_shell` | `executeBash` | Pattern compression for git/npm/test output |
| `mcp_lean_ctx_ctx_search` | `grepSearch` | Compact, .gitignore-aware results |
| `mcp_lean_ctx_ctx_tree` | `listDirectory` | Compact directory maps with file counts |
## When to use native Kiro tools instead
- `fsWrite` / `fsAppend` — always use native (lean-ctx doesn't write files)
- `strReplace` — always use native (precise string replacement)
- `semanticRename` / `smartRelocate` — always use native (IDE integration)
- `getDiagnostics` — always use native (language server diagnostics)
- `deleteFile` — always use native
## Session management
- At the start of a long task, call `mcp_lean_ctx_ctx_preload` with a task description to warm the cache
- Use `mcp_lean_ctx_ctx_compress` periodically in long conversations to checkpoint context
- Use `mcp_lean_ctx_ctx_knowledge` to persist important discoveries across sessions
## Rules
- NEVER loop on edit failures — switch to `mcp_lean_ctx_ctx_edit` immediately
- For large files, use `mcp_lean_ctx_ctx_read` with `mode: "signatures"` or `mode: "map"` first
- For re-reading a file you already read, just call `mcp_lean_ctx_ctx_read` again (cache hit = ~13 tokens)
- When running tests or build commands, use `mcp_lean_ctx_ctx_shell` for compressed output
<!-- lean-ctx-compression -->
OUTPUT STYLE: concise
- Bullet points over paragraphs
- Skip filler words and hedging ("I think", "probably", "it seems")
- 1-sentence explanations max, then code/action
- No repeating what the user said
<!-- /lean-ctx-compression -->
© yvgude · Apache-2.0 · yvgude/lean-ctx