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.

Current documented CLI API: 0.4.x.

Install

npm install -g @jarkkojs/readseek

Or build the native binary from source:

cargo build --release

Common commands

readseek detect src/main.rs
readseek read src/main.rs --start 10 --end 20
readseek map src/main.rs
readseek check src/main.rs
readseek symbol src/main.rs --name run
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

Use --stdin <path> with detect, read, map, check, symbol, and identify to analyze unsaved editor buffers while still providing a path for language detection:

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

Use def --from-identify to pipe identify JSON into definition lookup:

readseek identify src/main.rs:42 --column 8 | readseek def --from-identify src --format plain

Images

detect reports format, dimensions, and animation status for images. Add a vision flag to analyze image contents with the SmolVLM-500M vision model:

readseek detect screenshot.png --transcribe  # text + per-region bounding quads
readseek detect photo.jpg --caption        # detailed natural-language caption
readseek detect photo.jpg --objects        # object labels + bounding boxes

The flags can be combined; the model loads once per invocation. The model files (~0.4 GB GGUF + ~0.2 GB multimodal projection) 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 and takes a few to tens of seconds 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

The JavaScript npm wrapper is licensed under Apache-2.0. The Rust source and native binaries are licensed under LGPL-2.1-or-later. Corresponding source for each published native binary is available from the GitHub repository tag that matches the package version.

readseek downloads the SmolVLM-500M vision model (ggml-org/SmolVLM-500M-Instruct-GGUF, quantized from HuggingFaceTB/SmolVLM-500M-Instruct) into the user cache directory on first use. It is licensed under Apache-2.0.