Read Modes - How lean-ctx Reads Files

ctx_read supports 10 distinct modes, each optimized for a different situation. The right mode can save 74-99% of tokens compared to reading raw files.

Decision Tree: Which Mode?

Start here to pick the optimal mode for your situation:

Q1:

Will you edit this file?

Yes → Use full (first read), then diff (subsequent reads)
No → Continue to Q2

Q2:

Do you need the file's role/API surface, or line-level detail?

Role/API → Use map (85-95% savings)
Signatures → Use signatures (87% savings)
Line detail → Continue to Q3

Q3:

Is the file large (>500 lines) or contains boilerplate?

Large + boilerplate → Use entropy (60-85% savings)
Large + comments → Use aggressive (20-40% savings)
Only specific lines → Use lines:N-M
Not sure → Use auto (LeanCTX picks for you)

Q4:

Is there an active task set?

Yes → Use task (filters to task-relevant lines + graph context)
Just a pointer → Use reference (~1 line, 0 content)

Mode Comparison Table

Mode	Output	Token Savings	Best For
`auto`	Varies - selects best mode	Best-effort	When unsure which mode to use
`full`	Complete file + structured headers	~99% on re-reads	Files you'll edit
`map`	Dependencies, exports, API surface	85-95%	Understanding a file's role
`signatures`	All function/class/type signatures	~87%	Understanding API surfaces
`diff`	Only changed lines since last read	80-97%	Checking recent changes
`aggressive`	Full file minus comments + whitespace	20-40%	Verbose files with many comments
`entropy`	Shannon-filtered, deduplicated	60-85%	Files with repetitive patterns
`task`	Task-relevant lines + graph context	Highly variable	Task-driven development
`reference`	1-line pointer (no content)	~99.9%	Keeping track of files
`lines:N-M`	Specific line ranges	Proportional	Surgical edits in large files

Auto Mode

When you use mode=auto (or omit the mode parameter), lean-ctx selects the optimal mode based on file size, language, whether the file is cached, and the current task context. This is the recommended starting point if you're unsure.

ctx_read src/server.rs --mode auto
→ [auto] resolved to map
  F2=server.rs [262L]
  deps: rmcp::model::, rmcp::handler::...
  exports: -
  API: fn tool_def(...), fn execute_command(...)
  [2135 tok saved (93%)]

Full Mode (Default)

Returns the complete file with structured headers (dependencies, exports, file references). The content is cached with a BLAKE3 hash. Subsequent reads of the same unchanged file return a compact cache-hit message (~13 tokens) instead of re-transmitting the full content.

# First read: full content
ctx_read auth.ts
→ F1=auth.ts 123L deps:db,crypto exports:createUser,validateSession
  [complete file content...]

# Second read: cache hit
ctx_read auth.ts
→ F1=auth.ts cached 2t 123L

Map Mode

Returns the dependency graph, export list, and API signatures without implementation details. Uses tree-sitter AST parsing across 18 languages for accurate extraction. Best when you need to understand a file's role without reading its implementation.

Signatures Mode

Extracts all function signatures, interface definitions, type aliases, and class declarations. More detailed than map - includes private functions, nested types, and multi-line signatures with compact type abbreviations (:s for string, :n for number).

Diff Mode

Shows only the lines that changed since the file was last cached. Requires a prior read of the same file. Only sends the delta, which can save 80-97% compared to re-reading the full file.

Task Mode (Graph-Driven)

The most intelligent mode. It filters the file down to task-relevant lines using an information bottleneck filter, then appends a Graph Context footer with related files (imports, imported-by, transitive dependencies, type providers).

Prerequisites:

Set a task via ctx_session action=task value="your task description"
Optionally build the project graph with ctx_graph action=build for richer context
Read with ctx_read path="..." mode=task

ctx_session action=task value="fix auth refresh token bug"
ctx_read src/auth/service.rs --mode task
→ F1=src/auth/service.rs 412L [task-filtered: 412→38]
  ...task-relevant lines only...
--- GRAPH CONTEXT (4 related files, 9180 tok) ---
  src/auth/token.rs [imports]
  src/http/middleware.rs [imported-by]
--- END GRAPH CONTEXT ---

Reference Mode

Ultra-compact: returns a single line with file metadata (line count, token estimate, type). No content is transferred. Use to register a file as "known" without spending tokens on it.

Lines Mode

Read only specific lines. Supports single lines, ranges, and comma-separated combinations:

lines:42 - single line
lines:10-80 - line range
lines:10-80,120,200-240 - multiple ranges

Instruction File Protection (v3.5.13)

Files recognized as agent instructions are always delivered in full mode, regardless of the requested mode. This prevents critical agent instructions from being compressed or stripped.

Protected files and directories:

SKILL.md, AGENTS.md, RULES.md, .cursorrules
Files in /skills/, /.cursor/rules/, /.claude/rules/ directories

The guard is applied in 5 code paths: resolve_auto_mode, predict_from_defaults, select_mode_with_task, auto_degrade_read_mode, and CLI read_cmd.

Markdown File Exemption

Markdown files (.md, .mdx, .txt, .rst) are exempt from the aggressive default bucket — they return full mode by default to preserve prose content.

Structured Headers

Every ctx_read response includes a structured header with persistent file references:

F1=auth.ts 123L
 deps db,crypto
 exports createUser,validateSession

F1, F2, ... - file reference IDs (persist across the entire session)
deps - imported modules (compact list)
exports - exported names

Reference these IDs in subsequent operations instead of full paths to save tokens (e.g., "edit F1:42" instead of "edit src/auth/service.ts line 42").