pi-snap-edit

Fast, precise line edits for Pi. Experimental.

Why

Pain points from agent workflow:

• Pi's built-in edit tools are safe and precise, but exact replacements can use a lot of tokens.
• Small mismatches can cause retries, especially in large or messy edits.
• Escaped strings, quotes, backslashes, regex, and templates can turn exact replacements into escape hell.
• For complex changes, agents often use ad-hoc Python scripts, which are harder to review.
• Indentation/whitespace mismatches cause expectedStartLine guard to fail despite visually matching content, requiring careful copy or the use of expectedStartLineMatch: "trim" + preserveIndent: true.
• Most search tools (rg -n, grep -n, src maps) naturally return line numbers, not custom anchors.

pi-snap-edit uses a narrower model: edit by line number with required start-line content guards, or exact target text with line/range selectors. It trades whole-block exact matching and ad-hoc scripts for smaller, easier-to-review tool calls; re-read before editing when line positions may have shifted.

Why not hash-line anchors

Earlier versions centered the main read-driven workflow on <line>:<hash>|<content> anchors. In practice, the first successful edit made the rest of the read output stale. Current read output uses line numbers instead.

Behavior

pi-snap-edit currently registers quick_edit and target_edit as preferred active editing tools. Use line-numbered edits when target lines are known; use target_edit when the stable handle is exact text/marker content instead.

| Need | Pi built-in edit | pi-snap-edit | | --- | --- | --- | | Small exact text replacement | Best when the exact old text is short and easy to quote | Use target_edit by exact target line/range, or quick_edit when line numbers are known | | Large block replacement | Requires sending the full exact old block | Replace by 1-indexed line/range with quick_edit | | Escape-heavy text (quotes, backslashes, regex, templates) | Can get noisy because old/new text must be escaped | Easier: replace whole lines or target a small marker | | Output from rg -n / grep -n | Usually needs another read or exact old text | Directly usable with line numbers and expectedStartLine | | Concurrent file changes | Exact old text must still match | Start-line guarded; re-read when line positions may have shifted | | Duplicate/repeated blocks | Exact text can be more precise | Use explicit line numbers plus expectedStartLine, or target_edit with line or range | | Reviewability | Shows exact replacement intent | Avoids ad-hoc scripts; tool output shows diff + line-numbered refreshed context |

Tool behavior:

• read output includes padded line numbers; offset reads keep absolute file line numbers.
• On session start, the extension removes Pi's built-in edit tool from the active set and adds quick_edit and target_edit.
• quick_edit performs atomic line/range replacements using 1-indexed line numbers; requires expectedStartLine for each edit.
• expectedStartLine guards the current start line only; it does not verify the full range or detect line shifts from insertions/deletions above.
• quick_edit defaults to exact guard matching. Use expectedStartLineMatch: "trim" plus preserveIndent: true when indentation/trailing whitespace is uncertain and replacement lines should inherit the current line indentation.
• substitute_edit registration is currently disabled; its engine remains exported for now.
• target_edit performs ordered exact-target operations: replace, delete, insert_before, and insert_after.
• For replace and delete, selectors are flexible: omit both line/range when the target is unique in the file; use line for one occurrence on a line; use range for every occurrence fully inside an inclusive line range; or combine line + range to scope by range and verify one selected occurrence intersects the line.
• insert_before and insert_after require line and insert full lines before/after the target occurrence.
• target_edit defaults to exact substring matching. Set matchMode: "trim" when indentation or trailing whitespace may differ: it compares whole lines after trimming, bounds the edit to the trimmed content so original indentation is preserved, strips replacement edge whitespace, rejects whitespace-only trim targets, and does not consume the following line ending.
• Line endings are preserved, including CRLF and no-trailing-newline files.
• Invalid quick_edit ranges/overlaps, invalid target_edit selectors/ranges, target misses, and expectedStartLine mismatches are rejected without partial writes.
• Failure hints may list moved/close matches with line numbers. Multi-line target misses can include first-line near matches, last-line near matches, and capped anchor block candidates. Fuzzy hints are diagnostic-only and never applied automatically.

target_edit quick shape

{
  "path": "src/file.ts",
  "ops": [
    {
      "type": "insert_after",
      "target": "const app = createApp();",
      "line": 1,
      "lines": ["app.use(logger);"]
    }
  ]
}

Rules: target is exact literal text by default; use matchMode: "trim" for whole-line whitespace-tolerant matching. replace/delete may use no selector, line, range, or line + range as described above. insert_before/insert_after require line. replace uses replacement text.

Install

pi install npm:pi-snap-edit

Or load locally from this checkout:

pi -e ./src/index.ts

Eval harness

This repo includes a small prompt-guideline eval harness. It compares "informed" tool calls that follow the documented guidance against simpler naive calls, then reports which guidelines changed outcomes.

npx tsx test/eval-guidelines.ts

Use it as a documentation sanity check when changing tool guidance or edit semantics; it is not a replacement for npm test.