Hash-anchored file editing for Claude Code, AI coding agents, and patch-safe automation.
Every line gets a stable xxh32 hash (42:a3). Patch by anchor, not by fragile text match. Stale reads are caught and rejected before they corrupt your work.
curl -fsSL "https://raw.githubusercontent.com/quangdang46/hashline/main/install.sh?$(date +%s)" | bashhashline ships a 6-tool MCP server that works with Claude Code, Codex, Cursor, Windsurf, Gemini CLI, and OpenCode. The installer auto-configures it.
# MCP stdio server (auto-wired by installer)
hashline mcp
# Read a file with hashes — agents copy anchors, not lines
hashline read src/auth.js --json
# Patch by anchor — survives nearby edits
hashline patch src/auth.js 'SWAP 2:b2:'
+ const decoded = jwt.verify(token, env.SECRET)
# Dry-run before applying
hashline patch src/auth.js 'DEL 3' --dry-run --jsonOutput conventions
- stdout = data only (file content, patch result, JSON)
- stderr = diagnostics, warnings
- exit 0 = success, exit 1 = stale-read rejection or no-op
AI coding agents (str_replace, sed, bespoke edit LLM tools) routinely botch file edits. The pattern is always the same: whitespace mismatch, stale context, a } that was supposed to close a block but grabbed the wrong one instead. Each failure costs 10–60 seconds in retry round-trips, and after the first successful edit, every remaining line number shifts — so targeting by number alone is fragile.
hashline replaces fragile text-matching with content-hashed line anchors (42:a3). Read a file once and every line comes with a stable xxh32 hash. Patch using those anchors — insertions, deletions, swaps, and block replacements all reference hashes, not line text or numbers. If the file changed between read and apply, hashline rejects the patch with a clear error. No silent corruption, no wasted retries.
| Feature | What it does |
|---|---|
| Stable anchors | xxh32 hashes survive nearby edits; re-targeting is one anchor change |
| Stale-read detection | Hard error if file changed between read and patch |
| Block-aware ops | SWAP.BLK / DEL.BLK / INS.BLK.POST for brace-delimited, indent-based, and Ruby def…end blocks |
| Atomic writes | Temp file + rename. No partial writes, no torn edits |
| Multi-op patches | Several SWAP/DEL/INS in one pass via stdin pipe |
| MCP server | 6-tool stdio MCP for Claude Code, Codex, Cursor, and friends |
| Daemon mode | Background JSON-RPC over Unix socket or HTTP |
| Dry-run preview | --dry-run shows diff before applying |
| Dimension | hashline | str_replace (built-in) |
sed |
|---|---|---|---|
| Stable anchors | ✅ xxh32 hash 42:a3 |
❌ Exact text match | ❌ Fragile regex |
| Stale-read detection | ✅ Hard error on mismatch | ❌ Applies blindly | ❌ Applies blindly |
| Block replacement | ✅ SWAP.BLK / DEL.BLK / INS.BLK.POST | ❌ Line-granularity | ❌ Line-granularity |
| Atomic writes | ✅ Temp file + rename | ✅ Temp file + rename | ❌ In-place (torn writes possible) |
| Multi-op batches | ✅ stdin *** Begin Patch |
❌ One replacement per call | ✅ -e flag chaining |
| Dry-run preview | ✅ --dry-run with diff |
❌ Not supported | ❌ Not supported |
| MCP server | ✅ hashline mcp (6 tools) |
N/A | N/A |
| Setup | Single Rust binary ~280 µs anchor resolution | Built into agent | POSIX standard |
# 1. Read a file — every line gets a hash
hashline read src/app.ts
# ──[src/app.ts#1A2B]─────────────────────────────
# 1:a1| import { verify } from 'jwt'
# 2:b2| const token = req.headers.authorization
# 3:c3| if (!verify(token, SECRET)) throw 401
# 4:d4| return decode(token)
# 2. Build a patch using the anchor
hashline patch src/app.ts 'SWAP 3:c3:
+ if (!token) throw new AuthError("missing token")'
# 3. Apply — atomic write, no partial file
# File is updated in-place with a temp-file+rename| Principle | Rationale |
|---|---|
| Anchors over content matching | xxh32 hashes are stable, short, and easy for agents to copy. Re-targeting after an edit is a single anchor change. |
| Stale-read is a hard error | If the file changed between read and patch, hashline refuses — the agent must re-read and re-anchor. Better fail-fast than corrupt. |
| Block awareness | Brace-delimited, indentation-based, and Ruby def…end block ops eliminate the "find the closing brace" problem that LLMs struggle with. |
| Atomic writes only | Temp file + rename. No partial writes, no torn edits. |
Why hashline is not a drop-in for sed or str_replace:
| Edge case | Reality |
|---|---|
| Text-search edits | hashline does not support sed s/old/new/g — use sed when you need regex replacement across non-hashable text |
| Line-number targeting | hashline accepts line-number targets as fallback, but the design is anchor-first |
| Interactive editing | hashline is batch-oriented (read → patch) — for interactive editing use your editor |
hashline is developed based on the idea of hash-anchored line editing. Thanks to can1357 for the original oh-my-pi.
# macOS / Linux — curl pipe
curl -fsSL "https://raw.githubusercontent.com/quangdang46/hashline/main/install.sh?$(date +%s)" | bash
# Windows PowerShell
irm "https://raw.githubusercontent.com/quangdang46/hashline/main/install.ps1" | iex
# From source
cargo install --path crates/coreThe installers auto-detect your platform, fetch the matching binary from GitHub Releases, verify the SHA-256, and atomically install to ~/.local/bin/hashline. They also auto-detect supported MCP hosts (claude-code, codex, cursor, windsurf, vscode, gemini, opencode) and upsert a hashline MCP server entry for each.
Beyond the MCP server, hashline ships thin-wrapper packages for agent hosts that
prefer native read/edit tools over MCP. Both shell out to the hashline binary —
they never reimplement hashing, staleness detection, or merge recovery in TypeScript.
| Package | Host | Tools | Install |
|---|---|---|---|
integration/pi-hashline |
pi-coding-agent | overrides built-in read/edit |
pi install git:github.com/quangdang46/hashline#<path> (see package README) |
integration/opencode-plugin |
OpenCode | hashline_read, hashline_edit |
opencode.json plugin: ["@scope/hashline-opencode-plugin"] + disable native edit |
Both require the hashline binary on PATH (or HASHLINE_BIN). See each package's
README.md and integration/CONTRACT.md for the exact CLI
contract and setup.
# 1. Read a file with snapshot hashes
hashline read src/auth.js
# 2. Apply a single-line patch
hashline patch src/auth.js 'SWAP 2:
+ const decoded = jwt.verify(token, env.SECRET)'
# 3. Apply a range
hashline patch src/auth.js 'SWAP 2..4:
+ return decoded'
# 4. Delete a line
hashline patch src/auth.js 'DEL 3'
# 5. Dry-run first
hashline patch src/auth.js 'DEL 3' --dry-run
# 6. Block operations
hashline patch src/mod.rs 'SWAP.BLK 12:
+fn replaced() {
+ // new body
+}'
# 7. Multi-op via stdin (no intermediate file)
hashline patch src/auth.js - <<'EOF'
*** Begin Patch
SWAP 5:1a2b:
+ const decoded = jwt.verify(token, env.SECRET)
DEL 9
*** End Patch
EOF| Command | Description | See also |
|---|---|---|
read |
Read file with [path#HASH] + `LINE:hash |
content` |
patch |
Apply SWAP/DEL/INS/BLK edits | hashline guide → Patch Operations |
write |
Write content to a new file (--force overwrites) |
|
find-block |
Find enclosing brace/indent/Ruby block around anchor | |
remove |
Delete a file | |
rename |
Rename (move) a file | |
remove |
Delete a file | |
guide |
Interactive user guide — always matches your binary | built-in |
serve |
daemon over Unix socket or HTTP | hashline guide → Daemon Mode |
mcp |
MCP stdio server (6 tools) | hashline guide → MCP Mode |
┌─────────────────┐
│ hashline read │
│ [file#1A2B] │
│ 1:a1|content │
└────────┬────────┘
│ copy anchor
▼
┌──────────────────────────┐
│ Build patch string │
│ SWAP 2:b2: │
│ +new content │
└────────┬─────────────────┘
│
┌────────▼─────────┐ ┌──────────────┐
│ hashline patch │──│ --dry-run │
│ file.patch │ │ preview │
└────────┬─────────┘ └──────────────┘
│
┌────────▼─────────┐
│ File updated │
│ (atomic write) │
└──────────────────┘
Block-aware resolution by extension:
.rs .js .ts .go .java .c .cpp .h .cs → brace-balanced { }
.py .verse → indentation-based
.rb → def … end matching
Payload lines starting with + have the + prefix consumed as a sigil marker. To produce a literal leading + or -, use the escapes:
| Input | Output | When to use |
|---|---|---|
++text |
+text |
Content that literally starts with a + sign |
+-text |
-text |
Content that literally starts with a - (e.g. Markdown list items). Without the escape, bare - lines emit a warning but are still preserved. |
A blank line inside a payload block is written as a bare empty line (no + prefix):
INS.POST 2:
+First paragraph.
+Second paragraph.
| Edge case | Reality |
|---|---|
| Not a sed replacement | hashline does not support regex find-and-replace across text — use sed for that |
| Anchor-first design | Line-number targeting works as fallback, but the tool is optimized for hash-based edits |
| Batch-oriented | read → patch workflow, not interactive editing |
| No tree-sitter | Block resolution is syntactic (brace depth, indent, end), not AST-based |
| Error | Likely Cause | Fix |
|---|---|---|
I/O error: No such file or directory |
Path does not exist | Check path + permissions |
line 2 content changed since last read |
File modified after read |
hashline read <file> retry patch |
hash 'ff' not found in demo.txt |
Anchor copied from wrong read | Re-read + copy fresh hash |
hash 'ab' matches 3 lines |
4-hex hash is ambiguous | Use line-qualified 2:ab |
Does hashline work with Claude Code's built-in tools? Yes — hashline mcp exposes a stdio MCP server with 6 tools (read, patch, write, find_block, remove_file, rename_file) that any MCP-capable agent can call. The install script auto-configures it.
Can I use hashline as a daemon? Yes — hashline serve runs a background daemon that accepts JSON-RPC over Unix socket (default: ~/.hashline/daemon.sock) or HTTP (--http 17300). Set HASHLINE_URL to route CLI calls through it.
Is it fast? Anchor resolution on a 10k-line file takes ~280 µs. Full patch (parse + apply) is ~297 µs. File I/O dominates at scale, not hashing.
What about tree-sitter? hashline does not use tree-sitter. Block resolution is purely syntactic (brace depth, indentation, end keyword). This keeps the binary small and startup instant.