Tool
read
Not file reading — querying the index for a precise cut. The parse already happened, so read returns the richest representation that fits the budget you set: full content if it fits, else structure, else a headline. Everything else on this page is a way of choosing what “richest” means.
The shape of a directory for 292 tokens. Ask for tree: headlines instead and every file
arrives with a line describing what it is for — still without opening one.
Run it yourself
Or say it to your agent
“give me a map of the src directory without reading any files”
Parameters
| Parameter | What it does | |
|---|---|---|
| uri | required | The address. Globs allowed in the path, fragments after it, one modifier at the end. Join several with ;. |
| tokenBudget | optional | A contract, not a hint: you get the richest representation that fits inside it. Start at 800–2000 and raise it when the answer is worth more. |
The sixteen modifiers
Append => modifier to any address to choose what comes back. One modifier per address; those
written with a colon take a parameter after it.
| Modifier | Parameter | What comes back |
|---|---|---|
| content | — | Full text with line numbers. Assembles resolvable @ references in place. |
| content: | literal | Raw source, references left untouched. Use it when you are about to edit the file. |
| content: | preview | The reference manifest and its projected cost, without fetching the targets. |
| structure | — | Signatures without bodies — classes, methods, headings. |
| headline | — | One line summarising each file, as a flat list. |
| tree: | folders / files / headlines | A directory tree at the detail level you ask for. Folders is cheapest. |
| find: | keywords | Semantic search inside the matched files, with snippets. |
| similar: | seed URI | Rank the scope by likeness to a seed document, using stored vectors. |
| grep: | text | Literal text search. All-lowercase is case-insensitive; any capital makes it exact. |
| regex: | pattern | Regular-expression line search across the scope. |
| where | local / remote | Resolve the address to a path on disk, or to a GitHub URL. |
| changes | — | Working-copy git changes in the scope, grouped staged, unstaged, untracked. |
| concepts | — | The invariants this repository has recorded about the scope, most specific first. |
| history: | query (optional) | The commits behind the matched files, symbols, or lines. A query reranks them by relevance. |
| blame | — | Line attribution grouped by commit — down to a single symbol. |
| question: | your question | A synthesised answer over the matched content, with citations. |
| lint: | errors / warnings | Diagnostics aggregated from annotations in the scope. |
| coverage: | uncovered / content | Coverage as a symbol summary, the uncovered gaps, or source with an execution gutter. |
Composing them
Glob, fragment, and modifier are independent, so they multiply. The whole address grammar is available in front of every one of these.
Budget is a contract
Breadth and depth trade against each other inside the number you set. A glob matching hundreds of files spends the budget on headlines; the same budget on ten files buys the structure of each; on one file it buys the whole thing. Narrow the address to go deep, widen it to go broad.
This page names what exists. The depth behind every name — the bounds, the failure modes, how they compose — ships inside the binary at help:///, and answers to explore and read exactly like your code does. Install it, and your agent has the manual.