pi-readseek

pi-readseek adds ReadSeek's anchored file operations, structural search, symbol navigation, and document tools to Pi. Built-ins remain available unless overrideTools maps read, edit, write, or grep to a ReadSeek-backed implementation. The read override runs ReadSeek's digest command; it does not add a separate readSeek_read tool.

Install

pi install npm:pi-readseek

The package depends on @jarkkojs/readseek, which supplies the native binary on supported platforms. The extension uses that packaged binary exclusively; an unresolved binary indicates a broken installation rather than falling back to an unrelated readseek executable on PATH.

Tools

Tool	Purpose
readSeek_edit	Apply hash-verified edits to an existing text file
readSeek_write	Create or replace a complete text file and return anchors
readSeek_grep	Search text or regex and return edit-ready anchors
readSeek_search	Search AST patterns
readSeek_def	Find symbol definitions
readSeek_refs	Find identifier usages, optionally scoped to a cursor binding
readSeek_rename	Rename a cursor symbol; set apply: false to preview the plan
readSeek_digest	Native digest envelope: map, diagnostics, identity, content, metadata
readSeek_view	View or narrow a structural document index (PDF first); optional asset vision

The extension also tells Pi to get fresh anchors before editing and to run readSeek_digest with diagnostics after source edits.

Settings

Add a readseek object to ~/.pi/agent/settings.json (global) or .pi/settings.json (project). Project settings override matching global values. Defaults:

{
  "readseek": {
    "overrideTools": [],
    "imageMode": "auto",
    "syntaxValidation": "warn",
    "timeoutMs": 120000,
    "grep": {
      "maxLines": 2000,
      "maxBytes": 51200
    },
    "display": {
      "grep": "compact",
      "edit": "expanded",
      "write": "expanded"
    }
  }
}

• overrideTools: any of "read", "edit", "write", and "grep".
• imageMode: controls standalone images when digest overrides read. "auto" passes the prepared image to image-capable Pi models and otherwise runs local analysis, "on" always runs local analysis, and "off" skips the image. Local analysis defaults to all and also supports ocr, caption, and objects through visionMode. The namespaced readSeek_digest tool applies visionMode directly, including none. Documents use readSeek_view with optional visionMode and visionLevel. Local analysis uses Qwen3-VL-2B-Instruct.
• syntaxValidation: "warn" (write and warn), "block" (abort), or "off". Validation triggers only when an edit increases parser error or missing-node counts.
• timeoutMs: native command timeout in milliseconds.
• grep.maxLines and grep.maxBytes: output limits; larger values are clamped to the defaults.
• display: initial "compact" or "expanded" state for grep, edit, and write results.

Development

npm install
npm test
npm run typecheck

License

pi-readseek is Apache-2.0; see LICENSE. @jarkkojs/readseek is licensed separately under Apache-2.0 AND LGPL-2.1-or-later.