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.

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>

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|     }

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