Skip to main content
rule KR Kiro CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/lean-ctx.md
Open on GitHub

What 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 .gitignore awareness
  • 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 createUser and 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set4

Project sponsors

Companies that keep this analytics open