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.

Install

pi install npm:pi-readseek

The package depends on @jarkkojs/readseek, which supplies the native binary on supported platforms.

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": {
      "read": "compact",
      "grep": "compact",
      "edit": "expanded",
      "write": "expanded"
    }
  }
}

• overrideTools: any of "read", "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 read, 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.