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 edit, write, or grep to a ReadSeek-backed implementation.

Install

pi install npm:pi-readseek

The package depends on @jarkkojs/readseek, which supplies the native binary on supported platforms. A user-managed readseek on PATH (for example a system-package or developer install) takes precedence over the bundled binary.

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 "edit", "write", and "grep".
• imageMode: "auto" uses Pi's native image input when available, "on" always runs local analysis, and "off" skips standalone images. Image modes are all, ocr, caption, and objects; in "auto", none returns a prepared image without local analysis. 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.