Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single path string.
Parameters
path— required. Local path, internal URI (skill://,agent://,artifact://,memory://,rule://,local://,vault://,mcp://), or URL. Append:<sel>for line ranges, raw mode, or special modes (e.g.src/foo.ts:50-200,src/foo.ts:raw,db.sqlite:users:42).
Selectors
Append :<sel> to path. The bare path falls back to the default mode.
- (none) — parseable code → structural summary (signatures kept, bodies elided); other files → read from the start (up to {{DEFAULT_LIMIT}} lines).
:50/:50-— read from line 50 onward.:50-200— lines 50–200 inclusive.:50+150— 150 lines starting at line 50.:20+1— exactly one line.:5-16,960-973— multiple ranges in one call (sorted, overlaps merged).:raw— verbatim text; no anchors, no summary, no line prefixes.:2-4:rawor:raw:2-4— range AND verbatim; the two compose in either order.:conflicts— one-line-per-block index of every unresolved git merge conflict.
Files
-
Reading a directory path returns a depth-limited dirent listing. {{#if IS_HL_MODE}}
-
Reading a file with an explicit selector emits a file snapshot tag header and numbered lines:
¶src/foo.ts#0athen41:def alpha():. Copy the¶PATH#TAGheader for anchored edits; ops use bare line numbers. NEVER fabricate the tag. {{else}} {{#if IS_LINE_NUMBER_MODE}} -
Reading a file with an explicit selector returns lines prefixed with line numbers:
41|def alpha():. {{/if}} {{/if}} -
Parseable code without a selector returns a structural summary: declarations kept, large bodies collapsed to
..(merged brace pair) or…(standalone). Summarized output ends with a footer demonstrating the multi-range selector you can use to recover the elided bodies, e.g.:[NN lines elided; re-read needed ranges, e.g. <path>:5-16,40-80]Re-issue only the relevant range(s) using the multi-range selector (e.g.
<path>:5-16,120-200). NEVER guess what's inside../…— those markers carry no content. NEVER re-read the whole file or use:rawwhen targeted ranges suffice.
Documents & Notebooks
Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (.ipynb) are shown as editable # %% [type] cell:N text; edits round-trip back to the underlying JSON preserving notebook metadata. Add :raw to a notebook to bypass the converter and read the JSON directly.
Images
{{#if INSPECT_IMAGE_ENABLED}}
Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call inspect_image with the path and a question describing what to inspect.
{{else}}
Reading an image path returns the decoded image inline (PNG, JPEG, GIF, WEBP) for direct visual analysis.
{{/if}}
Archives
Supports .tar, .tar.gz, .tgz, .zip. Use archive.ext:path/inside/archive to read a member, and append a normal selector to the inner path: archive.zip:dir/file.ts:50-60.
SQLite
For .sqlite, .sqlite3, .db, .db3:
file.db— list tables with row countsfile.db:table— schema + sample rowsfile.db:table:key— single row by primary keyfile.db:table?limit=50&offset=100— paginated rowsfile.db:table?where=status='active'&order=created:desc— filtered rowsfile.db?q=SELECT …— read-only SELECT query
URLs
- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.
:rawreturns untouched HTML; line selectors (:50,:50-100,:50+150) paginate the cached fetched output.- Bare
host:portURLs collide with the selector grammar — add a trailing slash before the selector:https://example.com/:80.
Internal URIs
skill://<name>, agent://<id>, artifact://<id>, memory://root, rule://<name>, local://<name>.md, vault://<vault>/<path>, mcp://<uri> resolve transparently and accept the same line selectors as filesystem paths. Use artifact://<id> to recover full output that a previous bash/eval/tool result spilled or truncated.