---
description: "lean-ctx: ALWAYS use ctx_read/ctx_shell/ctx_search/ctx_tree instead of Read/Shell/Grep/ls"
globs: **/*
alwaysApply: true
---
# lean-ctx — Context Engineering Layer
CRITICAL: NEVER use native Read, Shell, Grep, or ls tools. ALWAYS use lean-ctx MCP equivalents below.
## Tool Mapping (MANDATORY)
| FORBIDDEN | USE INSTEAD | Why |
|-----------|-------------|-----|
| `Read` | `ctx_read` | Session caching, 8 compression modes, re-reads cost ~13 tokens |
| `Shell` | `ctx_shell` | Pattern-based compression for git, npm, cargo, docker, tsc |
| `Grep` | `ctx_search` | Compact context, token-efficient results |
| `ls`, `find` | `ctx_tree` | Compact directory maps with file counts |
## ctx_read Modes
- `full` — default, cached read (use for files you will edit)
- `map` — dependency graph + exports + key signatures (use for context-only files)
- `signatures` — API surface only
- `diff` — changed lines only (use after edits)
- `aggressive` — syntax stripped
- `entropy` — Shannon + Jaccard filtering
- `lines:N-M` — specific range
Re-reads cost ~13 tokens. File refs F1, F2.. persist across the session.
Set `fresh=true` on ctx_read to bypass cache when spawned as a subagent or after context compaction.
## Default Strategy
- Reading for context → `map`
- Reading to understand API → `signatures`
- Reading to edit → `full`
- Re-reading → just call `full` again (cache returns ~13 tokens)
## Session Management
- `ctx_compress` at >10 turns — creates memory checkpoint
- `ctx_metrics` — hard numbers on what was saved
- `ctx_benchmark` — find optimal mode for a file
- `ctx_session load` — on new chat, restore previous session
## Proactive Tools
Use without being asked:
- `ctx_compress` — when context grows large, create checkpoint
- `ctx_metrics` — periodically verify token savings
## Write, StrReplace, Delete, Glob
These have no lean-ctx equivalent — use them normally.
## CRP v2 — Compact Response Protocol
Every token costs money. This applies to input, output, AND thinking tokens.
### Thinking Reduction (saves 30-60% thinking tokens)
1. Parse task first, then act. Don't explore when you already know the answer.
2. One hypothesis, test it. Don't enumerate 5 approaches — pick the most likely, try it.
3. Stop thinking when you have the answer.
4. Use structured context. lean-ctx headers tell you deps/exports — don't re-read files to find imports.
5. File ref tracking: F1=auth.ts means F1 everywhere in this session.
### Output Reduction (saves 50-80% output tokens)
1. NO prose. Just code and results.
2. NO echoing content that was just read.
3. Summarize tool results: 1 line max.
4. Show edits only — not surrounding unchanged code.
5. Batch tool calls. One message, multiple calls.
6. Never ask "shall I proceed?" — just do it.
7. Bullets > paragraphs. Tables > lists.
### Compact Notation
- `F:path` — reading file
- `+file` = created, `~file` = modified, `!file` = error
- `->` for results: "Built -> 18 pages, 0 errors"
## Model Selection
- Grep/search/explore → `model: "fast"`
- Simple edits (rename, add field, fix typo) → `model: "fast"`
- Multi-file refactors, architecture → default model
REMINDER: NEVER use native Read, Shell, Grep, or ls. ALWAYS use ctx_read, ctx_shell, ctx_search, ctx_tree. Every single time.