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:

Mode Comparison Table

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:

1. Set a task via ctx_session action=task value="your task description"
2. Optionally build the project graph with ctx_graph action=build for richer context
3. 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").