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.
• 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, counted literal substitutions, or exact target text with occurrence/count guards. 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 core edit tool	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 occurrence/count, 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 scope + occurrence/count
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.
• substitute_edit registration is temporarily disabled; its engine remains exported for now.
• target_edit performs ordered exact-target operations: replace, insert, and delete; each operation requires exactly one selector, occurrence or count.
• target_edit insert adds full lines before/after the line(s) containing the target; replace handles inline or multi-line text replacement.
• Line endings are preserved, including CRLF and no-trailing-newline files.
• Invalid ranges, count mismatches, target misses, overlapping edits, and expectedStartLine mismatches are rejected without partial writes.

target_edit quick shape

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

Rules: target is exact literal text; choose exactly one of occurrence or count; insert uses full lines, while replace uses replacement text.

Install

pi install npm:pi-snap-edit

Or load locally from this checkout:

pi -e ./src/index.ts