Read Modes

ctx_read supports 10 distinct modes, each optimized for a different situation. The right mode saves 60–90% of tokens compared to reading raw files; cached re-reads drop to ~13 tokens.

Decision Tree: Which Mode?

Start here to pick the optimal mode for your situation:

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 (Default)

auto is the default mode — when you omit the mode parameter, LeanCTX 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%)]

Suspect files always get full (#361): when the active task text names a file (e.g. "fix the sort in versioncmp.c"), auto forces full for that file ahead of any compression-favouring intent, so the agent always receives the body it needs to localise and edit the defect.

Structure-first cold reads (structure_first, #361): an opt-in bias (off by default; enable with the LEAN_CTX_STRUCTURE_FIRST env var) that lets auto prefer map on a cold read of a medium-sized source file. It stays capability-safe — the active-diagnostic, edit-failure, and small-file guards still force full.

ctx_multi_read honours auto per file (#421): batch reads no longer force every file to full — each file resolves to its own optimal mode, exactly like a single ctx_read. Omit mode (= auto) and reserve full for the read immediately before an edit.

Full Mode

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 (Lua and Luau are now first-class graph-indexed languages too, #360). Best when you need to understand a file's role without reading its implementation.

ctx_read src/auth/service.ts --mode map
→ F1=src/auth/service.ts [map] 214L (91% saved)
  DEPS: express, jsonwebtoken, bcrypt, ./db/users
  EXPORTS: authenticateUser, generateToken, refreshSession
  TYPES: AuthConfig, TokenPayload, SessionData
  API: authenticateUser(req,res)->Promise<User>
       generateToken(user:User)->string
       refreshSession(token:s)->Result<Session>

Non-code files (v3.6.18+): map mode also produces structured summaries for Markdown (heading outline), JSON (key structure with types), YAML (key hierarchy), TOML (section headers + key=value pairs), and lock files (workspace dependency summaries). Savings: 85-95% on large config and documentation files.

Export de-duplication (#361): map no longer repeats exports that the API: section already lists with full signatures — every export is shown exactly once (re-exports and const aliases the API can't capture still surface).

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).

ctx_read src/server/router.rs --mode signatures
→ F3=src/server/router.rs [signatures] 489L (87% saved)
  pub fn register_routes(app: &mut App) -> Result<()>
  pub fn handle_request(req: Request) -> Response
  fn validate_params(params: &Params) -> Result<()>
  pub struct RouterConfig { base_path: String, timeout: Duration }
  pub trait RouteHandler { fn execute(&self, ctx: &Context) -> Result<Response> }

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.

# After editing auth.ts (previously read as F1)
ctx_read src/auth/service.ts --mode diff
→ F1=src/auth/service.ts [diff] Δ3 lines (94% saved)
  ~L42: -  const token = jwt.sign(payload, SECRET)
        +  const token = jwt.sign(payload, SECRET, { expiresIn: '15m' })
  +L67:    validateRefreshToken(refreshToken: string): boolean

Aggressive Mode

Returns the full file with all comments, JSDoc blocks, and excessive whitespace stripped. Preserves all functional code. Best for verbose files where documentation comments dominate the token count.

ctx_read src/utils/helpers.ts --mode aggressive
→ F5=src/utils/helpers.ts [aggressive] 186L (32% saved)
  import { format } from 'date-fns';
  export function formatDate(d: Date): string {
    return format(d, 'yyyy-MM-dd');
  }
  export function slugify(text: string): string {
    return text.toLowerCase().replace(/\s+/g, '-');
  }

Entropy Mode

Uses Shannon entropy scoring and Jaccard similarity to filter out repetitive, low-information lines. Ideal for generated files, large configs, or schema files where many declarations follow the same pattern.

ctx_read src/generated/schema.ts --mode entropy
→ F4=src/generated/schema.ts [entropy] 1847L→312L (83% saved)
  Shannon filter: removed 1535 repetitive lines
  Kept: unique type definitions, variant patterns
  export interface UserSchema { id: string; email: string; ... }
  export interface OrderSchema { id: string; items: Item[]; ... }
  // 47 similar interfaces deduplicated

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.

ctx_read src/auth/service.ts --mode reference
→ F1=src/auth/service.ts [ref] 214L ~847tok ts

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

ctx_read src/server.rs --mode lines:42-48
→ F2=src/server.rs [lines:42-48] 7L
  42| pub fn start_server(config: &Config) -> Result<()> {
  43|     let addr = config.bind_address();
  44|     let listener = TcpListener::bind(addr)?;
  45|     info!("Server listening on {}", addr);
  46|     for stream in listener.incoming() {
  47|         handle_connection(stream?)?;
  48|     }

Anti-Inflation Invariant (v3.8.6)

A read never returns more tokens than the raw file. On a tiny file the one-line framing header (file reference + deps/exports summary) can be net overhead that only pays off across re-reads, so when framing would exceed the bare content, auto-resolved and full reads ship the file verbatim — a read is break-even at worst and a win whenever a compressed mode or a cached re-read applies. Explicitly requested views (map, signatures, lines:) are always honoured untouched, and the same guarantee now covers the one-shot CLI read path.

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").