readseek 0.4.34

structural source reader with stable line hashes
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# 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

```sh
npm install -g @jarkkojs/readseek
```

Or build the native binary from source:

```sh
cargo build --release
```

## Common commands

```sh
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:

```sh
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:

```sh
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 BLIP, YOLOv8-nano, and TrOCR models:

```sh
readseek detect photo.jpg --caption        # detailed natural-language caption
readseek detect photo.jpg --objects        # object labels + bounding boxes
readseek detect photo.jpg --ocr            # extracted text
```

The flags can be combined; each model loads once per invocation. 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:

```sh
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 BLIP caption model (a quantized GGUF from
`lmz/candle-blip`, with the tokenizer from `Salesforce/blip-image-captioning-large`),
the YOLOv8-nano object-detection model (`lmz/candle-yolo-v8`), and the TrOCR
printed-text model (`microsoft/trocr-base-printed`) into the `models/` subdirectory
of the user cache on first use. BLIP is licensed under `BSD-3-Clause`; YOLOv8-nano
is derived from Ultralytics YOLOv8 (`AGPL-3.0`); TrOCR is released by Microsoft.