snapedit

Snapshot-based file editing for AI agents — send only the NEW content, never the old block.

snapedit lets an editing agent (Claude Code, OpenCode, or any MCP client) edit files by sending only the new content — never the old text. Files are captured as immutable, content-addressed snapshots; edits reference the snapshot's 1-based line numbers, so lines shifted by prior edits elsewhere never silently misapply.

Agent                            snapedit                     Filesystem
  │  read_snapshot(path)            │
  ├────────────────────────────────►│  sha256(bytes) → blob_id
  │◄── blob_id + numbered page ────┤
  │                                 │   …(agent thinks)…
  │  apply_snapshot_patch(blob,     │
  │    from, to, NEW_CONTENT) ──────►│  base=snapshot · ours=live
  │                                 │  3-way merge OR splice
  │◄── ok:true / conflict / err ────┤
  │                                 │  atomic write + lock

Why

Direct rewrite tools force the agent to transmit the old text to locate a change; when a file changes between reads, misalignment silently corrupts files. snapedit replaces that with:

• Immutable snapshots — blob_id = sha256(bytes). The agent carries only the id; content is never re-sent.
• 3-way merge on apply — base = snapshot, ours = live file. Earlier edits (even insertions above the hunk) are preserved; the patch lands exactly where the snapshot said it should.
• Explicit conflicts — if the live file changed inside the hunk with different content, no write happens; a structured conflict is returned with previews of both sides.
• Safety over guesswork — ambiguous patches (hunk text duplicated in the live file) are refused with zero writes, never silently applied to the wrong occurrence.
• No shell transport — all bodies travel over stdio MCP (JSON-RPC lines). Large files are paged, never truncated by a shell.

Features

Feature	Details
Content-addressed store	~/.snapedit/blobs, sha256 verified on read, recency index
Cross-process safety	advisory locks, EEXIST-tolerant writes, stale-lock recovery
Concurrency	parallel edits: disjoint ranges both land; same range → clean conflict
Ambiguity safety	duplicated hunk text ⇒ refused, file proven byte-identical
Store GC	snapedit store prune [--days N] [--dry-run] (blobs never garbage-collected automatically)
Zero dependencies	plain Node.js ≥ 18, ESM

Install

git clone https://github.com/rianprei/snapedit.git
cd snapedit
npm test          # 55 tests, no deps required
npm link          # optional: expose `snapedit` on PATH

Quick start (CLI)

# snapshot + numbered page (default page 0, 300 lines)
snapedit read path/to/file.txt

# apply NEW content to snapshot lines 2..4 (1-based, inclusive)
snapedit apply path/to/file.txt <blob_id> 2 4 --content $'wrote new lines\n'

# where does the hunk map in the live file today?
snapedit locate path/to/file.txt <blob_id> 2 4

# run the MCP server over stdio
snapedit mcp

Claude Code configuration

Add an MCP server entry (Claude Code ~/.claude.json, or OpenCode's "type": "local" MCP):

{
  "mcpServers": {
    "snapedit": {
      "command": "/abs/path/to/snapedit/bin/snapedit",
      "args": ["mcp"]
    }
  }
}

Agent edit protocol (keep this short)

1. read_snapshot (page containing region) — remember blob_id.
2. apply_snapshot_patch(path, blob_id, from, to, new_content).
   • ok:true → done.
   • mode:"conflict" → re-read_snapshot, retry on the new snapshot.
   • kind:"snapshot_missing" → re-read_snapshot.
3. Never send the old text; never concatenate whole-file bodies yourself.

new_content is the exact replacement for snapshot lines [from..to] (1-based, inclusive). Multi-line edits work as a single new_content; the merge replays the hunk in snapshot coordinates, so earlier shifts don't break it.

Documentation

• Protocol — full JSON-RPC tool contracts, results, errors
• Architecture — modules, data flow, concurrency model
• Safety & invariants — ambiguity gate, conflict rules, corruption defenses, GC, locking
• Changelog
• Contributing

Security

See docs/SAFETY.md for the full property list. Highlights:

• Refuses ambiguous applies deterministically (match_count != 1 → write == false, proven byte-identical by sha256 in tests).
• Path-like blob_ids rejected (no filesystem traversal via the store).
• MCP input validation: malformed JSON-RPC → -32600, invalid tool args → bad_arg, never a crash of the server.
• Atomic write: temp file in same dir + rename → readers never observe partial content.

License

MIT — see LICENSE.