readseek

readseek reads source files and PDFs for scripts, editors, and coding agents. It returns compact JSON with stable line/hash anchors, symbol maps, parse diagnostics, AST matches, references, and rename plans.

Installation

Install the npm wrapper with a prebuilt binary:

npm install -g @jarkkojs/readseek

Or install the native program from crates.io:

cargo install readseek

Prebuilt binaries are available for macOS ARM64; Linux ARM64 and x64; and Windows x64. The Linux binaries are static glibc PIE executables.

To build and install from source:

make install

Plugins

Pi extension

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

pi install npm:pi-readseek

OpenCode plugin

The opencode-readseek plugin adds the same tools to OpenCode. Add it to opencode.json:

{
  "plugin": ["opencode-readseek"]
}

Vim plugin

The bundled readseek.vim plugin provides anchored reads, structural navigation, parse diagnostics, search, references, and renames. It requires Vim9 with +job, +channel, +popupwin, and +textprop; Neovim is not supported.

Install it with a Vim plugin manager, such as Plug 'jarkkojs/readseek', then run :ReadSeekInstall to install the matching prebuilt binary. Downloads are explicit by default.

Common commands

readseek detect src/main.rs
readseek read src/main.rs:10 --end 20
readseek read report.pdf --page 3
readseek view report.pdf --page 3
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

Global options must precede the command. For example, write JSON to a file with:

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

Prefix a target with stdin: to analyze an unsaved buffer while retaining a path for language detection and cursor addressing. This works with detect, read, map, check, symbol, and identify:

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

Images and PDFs

detect reports image metadata and PDF page counts. read returns bounded base64 images by default; select local analysis with --image:

readseek read photo.jpg                   # default: bounded base64 image
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
readseek read photo.jpg --image all       # caption, objects, and OCR in one pass

Vision analysis uses the balanced profile by default. Choose fast for lower latency or accurate for dense OCR and small objects:

readseek read photo.jpg --image caption --vision-profile fast
readseek read scan.png --image ocr --vision-profile accurate

--vision-diagnostics writes cache status, devices, token counts, timings, throughput, and peak RSS as JSON to stderr. --vision-benchmark N runs one warmup and N measured iterations for an image file:

readseek read fixture.png --image all --vision-benchmark 5 \
  >result.json 2>benchmark.json

Set READSEEK_VISION_THREADS to a positive integer to override Rayon's worker count. More workers may improve throughput at the cost of CPU and memory.

PDF reads return page-tagged Markdown and embedded images. Use --page to select a page; --image applies to each embedded image. After readseek init, view creates or reuses a structural PDF index that can be narrowed by page, node, kind, or depth. Line/hash suffixes, --end, --limit, and --language do not apply to visual files.

The Qwen3-VL-2B Q8_0 model and multimodal projector download lazily to the user cache and are checksum-verified. Inference uses ReadSeek's built-in CPU engine and can be slow.

Cache

readseek init [path] creates .readseek/maps/ and .readseek/def-index/. Map-dependent commands update them on demand and find .readseek/ by walking up from the target; --readseek-dir selects one explicitly. PDF indexes and extracted assets live in .readseek/documents/, while image analysis results are cached under .readseek/vision/. Image cache entries are profile-specific.

Documentation

For the complete CLI reference:

man ./man/man1/readseek.1

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

Licensing

The native readseek crate is licensed under LGPL-2.1-or-later. The npm wrapper and platform packages declare Apache-2.0 AND LGPL-2.1-or-later; plugin licenses are listed in their package directories. The downloaded Qwen model is licensed under Apache-2.0.