pi-hashline-edit

Hash-anchored read and edit tool override for pi-coding-agent — every line carries a content hash, so edits never land on the wrong line, even when the file has changed.

Inspired by oh-my-pi.

Why

LLMs edit code by quoting the text they see on screen. But by the time the edit runs, the file may have changed — a concurrent write, an earlier edit in the same turn, or drift from a stale read. The hashline protocol gives every line a short content hash, so edits carry verifiable references instead of raw text. Stale anchors are caught before they touch the file: no silent corruption, no wrong-line rewrites.

Features

• 📖 Hashline Read — file content with LINE#HASH: prefixes, providing verifiable line-level anchors
• ✏️ Anchored Edit — replace / append / prepend / replace_text, all validated against content hashes before applying
• 🔍 Grep — ripgrep-backed search returning LINE#HASH: anchors, usable directly in edit without a prior read (opt-in)
• 🔗 Chained Edits — successful edits return fresh anchors, enabling consecutive edits without re-reading
• 🛡️ Stale Anchor Recovery — 3-way snapshot merge attempts automatic recovery; on failure, returns fresh anchors for immediate retry
• 🚫 Strict by Design — no silent relocation, no fuzzy matching, no accidental overwrites
• ⚡ Atomic Writes — temp-file + rename, symlink and hardlink safe

Quick Start

pi install npm:pi-hashline-edit

Once installed, pi's read and edit tools are replaced by hashline versions. Reading a file will look like:

 8#VR:function hello() {
 9#KT:  console.log("world");
10#BH:}

To edit, reference LINE#HASH anchors from the read output:

{
  "path": "src/main.ts",
  "edits": [
    { "op": "replace", "pos": "9#KT", "lines": ["  console.log('hashline');"] }
  ]
}

If the file has changed since the last read, stale anchors are caught with explicit re-read guidance — no silent errors.

How It Works

read: tagged line output

Text files are returned with a LINE#HASH: prefix on every line:

• LINE — 1-indexed line number, left-padded for column alignment.
• HASH — content hash from the alphabet ZPMQVRWSNKTXJBYH; 2 characters by default, configurable up to 4 (see Configuration).

Optional parameters: offset (start line), limit (max lines), raw (plain content without prefixes).

Images (JPEG, PNG, GIF, WebP) are passed through as attachments. Binary and directory paths are rejected with a descriptive error.

edit: hash-anchored modifications

Edits use LINE#HASH anchors to target lines precisely. All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so line numbers stay consistent.

| Op | Purpose | Fields | |---|---|---| | replace | Replace one line (pos) or an inclusive range (pos + end). | pos required, end optional, lines | | append | Insert lines after pos. Omit pos to append at EOF. | pos optional, lines | | prepend | Insert lines before pos. Omit pos to prepend at BOF. | pos optional, lines | | replace_text | Replace an exact unique substring. Fails if not found or matches more than once. | oldText, newText |

grep: hashline-anchored search

Ripgrep-backed search returning LINE#HASH:content anchors in the same format as read output. These anchors can be passed directly into edit, closing the grep-to-edit loop without a separate round-trip.

• Pattern is regex by default; set literal: true for fixed-string search.
• Results respect .gitignore. Use path to scope and glob to filter by filename pattern.
• Set context (0–5) for surrounding lines; limit to cap matches (default 50, max 200).
• Off by default. Registered only when enabled in config ("grep": true) and rg is found on PATH.

Chained edits

After a successful edit, the result includes an --- Anchors A-B --- block with fresh LINE#HASH references for the changed region. These can be used directly in the next edit call without a full re-read, provided the next edit targets the same or nearby lines.

Configuration

Optional. Create ~/.pi/agent/hashline.json:

{
  "hashLength": 2,
  "grep": false,
  "replaceText": true
}

| Key | Default | Range | Meaning | |---|---|---|---| | hashLength | 2 | 2–4 | Characters per line hash. Longer hashes reduce false-accept risk at the cost of extra tokens per line. | | grep | false | boolean | Register the grep tool (also requires ripgrep on PATH). | | replaceText | true | boolean | Allow the replace_text op. Set false to enforce anchor-only edits. |

The file is read once at session start. A missing file means defaults. Invalid values fall back to defaults with a one-time warning.

Design Decisions

• No fallback relocation. Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
• Stale anchors: recover, then fail. A hash mismatch first attempts snapshot-merge recovery (3-way merge, fuzzFactor 0). If the snapshot is absent or the merge conflicts, [E_STALE_ANCHOR] tells the model to re-read; content-matched candidates are listed only when the anchor included a text hint.
• Strict patch content. If lines contains display prefixes or diff markers, the edit is rejected with [E_INVALID_PATCH]. The model must send literal file content.
• Noop loop guard. Three consecutive identical no-op edits throw [E_NOOP_LOOP], preventing the model from silently looping.
• Atomic writes. Files are written via temp-file-then-rename. Symlink chains are resolved; hard-linked files preserve the shared inode; permissions are preserved.
• Context-based hashing. Each line's hash includes its immediate neighbors (prev + curr + next), so identical lines in different contexts get different hashes, and editing line N only invalidates anchors for N−1, N, and N+1.

For more details, see the FAQ.

Development

git clone https://github.com/RimuruW/pi-hashline-edit.git
cd pi-hashline-edit
npm install

npm test          # Run tests (vitest)
npm run typecheck # Type checking
npm run lint      # Biome linter
npm run check     # All checks (typecheck + lint + knip + test)

Set PI_HASHLINE_DEBUG=1 to show an "active" notification at session start.

Contributing

Contributions are welcome! Feel free to open an Issue or submit a Pull Request.

Please run npm run check before submitting to ensure all checks pass.

Have questions? See the FAQ.

Credits

Thanks to can1357 for the original oh-my-pi implementation and the hashline technique.

License

MIT