pi-readseek

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

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.