Skip to content
Documentation

Read & shape context

Choose the right level of detail.

Use a map to navigate, a signature to understand an interface and source text to verify the implementation.

AvailableReviewed September 2026
Choose a representation for the task. Recover the full source when details matter.

Start with intent

ctx_read defaults to auto when you omit mode. Choose a mode explicitly when the task needs a particular representation. For discovery, start with ctx_compose or search so that a read has a clear target.

Mode Useful for What to check
auto A general first read The returned representation may omit detail
map File structure and API navigation Bodies are not the full implementation
signatures Function and type interfaces Language/parser support affects extraction
full Full-file inspection Cache and output processing can still affect delivery
lines:N-M A known region Use the correct line range for the current file
diff Changes since the cached read Compares the read cache, not Git HEAD; use git diff for repository changes
task Task-focused selection Relevant-looking lines may omit dependencies
entropy Dense information in a large file Ranking is a heuristic
aggressive A compact first representation Recover details before making exact edits
reference Reference-oriented delivery Follow the returned recovery instructions

The advertised mode list is not a closed enum. The reviewed parser also accepts these more specific representations:

Mode Behavior
raw Exact text without the usual framing
full-compact Headerless text with trailing whitespace removed
anchored / anchored:N-M Full text or a range with line/hash references for editing
lines:5,10-20 Several selected lines or ranges in one read
lines:-20 The last 20 lines of the file
cognitive A semantic chunk representation
mdl A structural description
density:0.40 A target-density compressed representation

Density and semantic modes are lossy views, not accuracy guarantees. The parser validates mode syntax; range selections use one-based, inclusive line numbers. See the exact read schema for the other inputs.

Read, then zoom in

These are MCP calls:

{"name":"ctx_read","arguments":{"path":"src/main.rs","mode":"signatures"}}
{"name":"ctx_read","arguments":{"path":"src/main.rs","mode":"lines:20-60","fresh":true}}

Use a range returned by your own search or signature view. The numbers above illustrate the argument format.

Exact text and edit anchors

raw: true requests verbatim content and a fresh read. It does not disable access boundaries or downstream security policies.

mode: "anchored" provides line/hash references for ctx_patch. Re-read after a conflicting edit; stale anchors are not a reason to force an overwrite.

When a compressed mode is served in full

Some files are delivered in full even when you request a compressing mode such as map, signatures, aggressive, entropy, task or reference:

  • Agent instruction files — AGENTS.md, CLAUDE.md, SKILL.md, GEMINI.md, LEAN-CTX.md and documents under skills/, .claude/rules/ and .cursor/rules/ — are always complete, on the MCP, CLI and helper read paths alike.
  • Files LeanCTX learned are always re-read in full. In releases after 3.11.4 this applies to explicit compressing modes too, not only auto. The read carries the notice [mode overridden: map -> full, reason=learned-full, pass fresh=true to keep the requested mode]; pass fresh: true when you really need the compressed view.

lines:, diff, raw and anchored always keep the requested view.

lines: windows, anchored:N-M and diff are partial reads: in releases after 3.11.4 reading a file window by window, and then in full, is never booked as a correction. The same holds for head, tail and sed -n through the shell.

Understand caching

An unchanged repeated read may return a compact reference. fresh: true bypasses the read cache, but is not the same as requesting raw text. If the answer needs an omitted detail, recover it rather than assuming the compact representation contains everything.

For shell archives and cached originals, continue with caching and recovery.

Sources & versions6 references Reviewed
  • mode.rsrust/src/tools/ctx_read/mode.rsReviewed checkout
  • file_io.rsrust/src/tools/ctx_read/file_io.rsReviewed checkout
  • ctx_read.rsrust/src/tools/registered/ctx_read.rsReviewed checkout
  • helpers.rsrust/src/tools/ctx_read/helpers.rsReviewed checkout
  • context_gate.rsrust/src/server/context_gate.rsReviewed checkout
  • quality-loop-v1.mddocs/contracts/quality-loop-v1.mdReviewed checkout
Core checkout
980380bfa0
Reviewed runtime
3.10.2
SDK release
1.1.0

Separate baselines for source, CLI/configuration and SDK contracts. Review does not certify every platform or integration.

Versions & compatibility