readseek

readseek is a structural source reader for scripts, editors, and coding agents. It emits pretty-printed JSON with stable LINE:HASH anchors, structural symbol maps, parse diagnostics, AST search matches, references, and rename plans.

Install

Build the native binary from source:

cargo build --release

Or install the npm wrapper:

npm install -g @jarkkojs/readseek

Pi extension

The bundled pi-readseek extension exposes ReadSeek's anchored file and structural-code tools in Pi:

pi install npm:pi-readseek

Common commands

readseek detect src/main.rs
readseek read src/main.rs:10 --end 20
readseek map src/main.rs
readseek check src/main.rs
readseek symbol src/main.rs:run --name
readseek identify src/main.rs:42 --column 8
readseek def src run --language rust --format plain
readseek refs src main --language rust --format plain
readseek search src 'fn $NAME() { $$$BODY }' --language rust
readseek rename src/main.rs --line 42 --column 8 --to renamed

To write JSON output to a file instead of stdout, place the global option before the command:

readseek --output result.json detect src/main.rs

Use a stdin: target prefix with detect, read, map, check, symbol, and identify to analyze unsaved editor buffers while still providing a path for language detection and a cursor address:

printf '%s\n' 'fn main() {}' | readseek identify stdin:scratch.rs:1 --column 4

Images

detect reports format, dimensions, and animation status for images. read runs vision analysis on images, defaulting to a caption; pass --image to choose the task (BLIP, YOLOv8-nano, TrOCR):

readseek read photo.jpg                  # default: caption
readseek read photo.jpg --image caption   # detailed natural-language caption
readseek read photo.jpg --image objects   # object labels + bounding boxes
readseek read photo.jpg --image ocr       # extracted text

Each invocation selects one mode; the requested model loads once. The model files (~258 MB BLIP GGUF + ~6 MB YOLOv8-nano + ~1.24 GB TrOCR) are downloaded lazily into the user cache directory on first vision use and reused on subsequent runs; a progress bar is shown while downloading when stdout is an interactive TTY. Inference is CPU-only; object detection and OCR take seconds and captioning up to a couple of minutes per image.

Cache

readseek init [path] creates a .readseek/ directory containing map cache files under maps/ and definition-index shards under def-index/. Commands discover that directory by walking up from the target path, or use the directory passed by --readseek-dir.

Documentation

The manual page is the authoritative CLI reference:

man man/man1/readseek.1

Pass --help to any command for command-specific usage.

Licensing

readseek is licensed under LGPL-2.1-or-later. The JavaScript npm wrapper is licensed under Apache-2.0.