# lean-ctx — Token Optimization

MANDATORY: For every file read, code search, shell command, or directory listing you MUST call the matching lean-ctx `ctx_*` MCP tool — never a built-in/native tool, and never answer a code question from memory without first calling one. This is not optional. If you catch yourself about to use a built-in Read/Grep/Shell/ls, STOP and call the `ctx_*` equivalent instead.

lean-ctx is configured as an MCP server. Always use lean-ctx MCP tools instead of built-in tools:

- Read files → `ctx_read(path, mode)` instead of built-in Read
- Shell commands → `ctx_shell(command)` instead of built-in Shell
- Search code → `ctx_search(pattern, path)` instead of built-in Grep
- List directories → `ctx_tree(path, depth)` instead of ls/find

ctx_read modes: auto, full, map, signatures, diff, task, reference, aggressive, entropy, lines:N-M.

Preferred workflow control: `ctx_workflow` (state + evidence + tool gating).

Fallback only if MCP is unavailable: prefix with `lean-ctx -c`:
- `lean-ctx -c git status`
- `lean-ctx -c cargo test`
- `lean-ctx -c npm install`

Write, StrReplace, Delete have no lean-ctx equivalent — use them normally.
