On this page
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.
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.mdand documents underskills/,.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]; passfresh: truewhen 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 & versions
- 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