ReadSeek

readseek turns source files, images, and documents into compact structured context for scripts, editors, and coding agents. Source output includes stable LINE:HASH anchors, symbol maps, parse diagnostics, AST matches, definitions, references, and verified rename plans.

Install

Choose one installation method:

npm install -g @jarkkojs/readseek  # Node 18+
cargo install readseek             # Rust 1.89+
make install                       # build this checkout and install the CLI + man page

make install supports PREFIX and DESTDIR. Prebuilt npm binaries are available for macOS ARM64, Linux ARM64/x64, and Windows x64; Linux builds are statically linked with musl.

Integrations

| Host | Package | Install | | ----------- | --------------------------------------------------------- | -------------------------------------------------------------------------- | | Pi | pi-readseek | pi install npm:pi-readseek | | OpenCode | opencode-readseek | Add opencode-readseek to opencode.json | | Claude Code | claude-readseek | Add this repository as a /plugin marketplace source | | Vim | readseek.vim | Install this repository with a plugin manager, then run :ReadSeekInstall |

In order to engage the use of the tool commands, add to your AGENTS.md:

## ReadSeek

- Prefer ReadSeek over regular read, edit, and grep tool commands.
- Use ReadSeek extensively and proactively.

CLI tour

Digest

readseek digest src/main.rs --at line:10 --end 20
readseek digest src/main.rs --at symbol:run
readseek digest src/main.rs --select metadata,map,diagnostics

digest always returns metadata plus the requested facets. content is the default; facets are combined with a comma.

Source reads emit records such as 42:a1b|let value = parse(input);. The line number locates the text; the short hash rejects most stale edits while tolerating whitespace-only changes.

Search and navigate

readseek def src run --language rust --format plain
readseek refs src run --language rust --format plain
readseek refs src/main.rs --at line:42:8
readseek search src 'fn $NAME() { $$$BODY }' --language rust
readseek search manual.pdf 'revocation' --limit 20

def, refs, and search accept a file or directory. In a Git work tree, directory searches include tracked/indexed and untracked non-ignored files by default. Use --git cached, --git others, or both to restrict the set; ignored requires others.

Edit

edit verifies all anchors and rejects stale or overlapping operations before writing. Requests are JSON files, or JSON on stdin by default:

readseek edit src/main.rs --request edits.json
readseek edit src/main.rs --request edits.json --apply --plan-hash <plan_hash>
printf '%s' '{"edits":[{"set_line":{"anchor":"42:a1b","new_text":"let value = 2;"}}]}' \
  | readseek edit src/main.rs --apply

A dry run returns the planned content and a plan_hash. Passing that hash during apply prevents a changed plan from being written.

Requests support anchored line replacement, range replacement, insertion, exact text replacement, and whole-symbol replacement. An empty new_text deletes an anchored line or range. --language overrides detection for symbol replacement.

Rename

A rename is a dry run unless --apply is present:

readseek rename src/main.rs --at line:42:8 --to renamed
readseek rename src/main.rs --at line:42:8 --to renamed --apply
readseek rename src/main.rs --at line:42 --to renamed --workspace . --apply

Rename plans report conflicts and hash-verified edits. Workspace mode extends the plan beyond the cursor file.

Global options and stdin

Global options must precede the command:

readseek --output result.json digest src/main.rs --select metadata
readseek --readseek-dir /tmp/project-index view report.pdf

Pass - as the path to read standard input. Use --stdin-name when a virtual path is needed for language detection or reporting. This works with digest and view:

printf '%s\n' 'fn main() {}' |
  readseek digest - --stdin-name scratch.rs --select identity --at line:1:4

Images and documents

digest reports image metadata and can return a bounded base64 image payload. Select local analysis explicitly:

readseek digest scan.png --vision-mode ocr --vision-level high

Vision modes are none, caption, objects, ocr, and all. Analysis starts at the low level; use medium or high only when more detail is needed.

PDF is the first supported document format. Document digestion ingests the whole document into the content-addressed structural cache and returns a JSON receipt whose state is built or reused. This makes digest suitable for cache-warming jobs. It does not return document pages or assets.

readseek init
readseek digest report.pdf
readseek view report.pdf --page 3
readseek view report.pdf --page 3 --vision-mode ocr

view is the document-content interface. It creates the same cache on a miss, then narrows the indexed structure by page, node, kind, or depth. Vision modes analyze the selected cached assets. --at and source range/language options do not apply to images or documents.

Image analysis runs locally on the CPU with Qwen3-VL-2B-Instruct. Its model files are downloaded and checksum-verified on first use.

Cache layout

readseek init [path] creates .readseek/ and refreshes its source indexes. Commands discover that directory by walking up from the target; use --readseek-dir to select one explicitly.

| Path | Contents | | ----------------------------- | ------------------------------------- | | .readseek/maps/ | Content-addressed source maps | | .readseek/def-index/ | Definition index | | .readseek/documents/ | Document indexes and extracted assets | | .readseek/vision/ | Level-specific image analysis results | | User cache readseek/models/ | Downloaded vision model files |

Development

Check

make ci
CI_MSRV=1 make ci  # optional MSRV check

Package

Packages the highest semver tag reachable from HEAD on the current branch (not necessarily the tip). Source is built from a detached worktree at that tag; this packaging script stays on tip so tooling fixes apply without a new tag. Artifacts land in npm/*/bin and artifacts/ on the caller tree.

Linux x64/arm64 and Windows x64 use cross and Docker. On Apple Silicon with Dory, x86_64 images run under FEX; packaging reaps the container if FEX leaves it stuck after cargo finishes. Cross builds default to CARGO_BUILD_JOBS=1 on Darwin to avoid FEX/virtiofs rlib corruption (override with CARGO_BUILD_JOBS).

darwin-arm64 builds with host cargo when packaging on darwin-arm64. From Linux, the same platform uses the local osxcross image ghcr.io/cross-rs/aarch64-apple-darwin-cross:local (Apple SDK; not redistributed).

make package
make package PLATFORMS='linux-x64 win32-x64'
PACKAGE_STRICT=1 make package

Release

After scripts/release.sh <version> and pushing the tag:

make ci
PACKAGE_STRICT=1 make package
make publish

make publish uses the highest semver tag reachable from HEAD (tip may be ahead). It publishes crates.io from that tagged tree, npm from local npm/*/bin artifacts, then uploads GitLab release tarballs when glab is available.

Reference

Run readseek --help or readseek <command> --help. To read the complete local manual:

man ./man/man1/readseek.1

License

• Native readseek: LGPL-2.1-or-later
• @jarkkojs/readseek npm wrapper: Apache-2.0 AND LGPL-2.1-or-later
• pi-readseek, opencode-readseek, and claude-readseek: Apache-2.0
• readseek.vim: MIT

Third-party attribution

• Qwen3-VL-2B-Instruct: Apache-2.0. Model files are downloaded at runtime and are not distributed with ReadSeek.
• Dwarf Seek 4: MIT. ReadSeek's Q4_K and Q6_K block decoding and dot-product code includes derived work.