hashline

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)" | bash

🤖 Agent Quickstart (MCP / Robot Mode)

hashline 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

# Patch by anchor — survives nearby edits (compact output)
hashline patch src/auth.js 'SWAP 2:b2:
+  const decoded = jwt.verify(token, env.SECRET)'
# OK src/auth.js#7f2a edits=1 changed=1
# ~2:f9|  const decoded = jwt.verify(token, env.SECRET)

# Dry-run before applying
hashline patch src/auth.js 'DEL 3' --dry-run

Output architecture — agent-first, token-minimal by default:

Output conventions

• stdout = data only (file content, patch result, JSON)
• stderr = diagnostics, warnings (ERR KIND key=val + HINT ... in compact mode)
• exit 0 = success, exit 1 = stale-read rejection or no-op

TL;DR

The Problem

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.

The Solution

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.

Why hashline?

How hashline Compares

Quick Example

# 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 (compact output)
hashline patch src/app.ts 'SWAP 3:c3:
+  if (!token) throw new AuthError("missing token")'
# OK src/app.ts#7f2a edits=1 changed=1
# ~3:e5|  if (!token) throw new AuthError("missing token")

# 3. Human-readable mode (full file after patch)
hashline patch src/app.ts --verbose 'SWAP 4:d4:
+  return decode(token)'

# 4. Structured JSON output
hashline patch src/app.ts --json 'SWAP 3:c3:
+  if (!token) throw new AuthError("missing token")'

Design Philosophy

Limitation vs Alternatives

Why hashline is not a drop-in for sed or str_replace:

Credit

hashline is developed based on the idea of hash-anchored line editing. Thanks to can1357 for the original oh-my-pi.

Installation

# 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/core

The 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.

Agent Host Integrations

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.

pi-coding-agent guide

The hashline-pi extension replaces pi's built-in file tools with the full hashline surface — anchors on every read, stale-safe batched edits, tree-sitter block ops, and colored diffs in the TUI.

# 1. Install the binary first (the package is a thin wrapper — it does not bundle it)
curl -fsSL "https://raw.githubusercontent.com/quangdang46/hashline/main/install.sh" | bash   # macOS / Linux
irm "https://raw.githubusercontent.com/quangdang46/hashline/main/install.ps1" | iex          # Windows (PowerShell)

# 2. Install the extension (project-local: add -l; global: omit it)
pi install npm:hashline-pi

Then /reload in pi and check /hashline-status. Requires binary >= 0.9.12. Binary off PATH? Set HASHLINE_BIN or { "binary": "..." } in ~/.pi/agent/hashline.json. Full details: integration/pi-hashline/README.md.

OpenCode

Both packages require the hashline binary on PATH (or HASHLINE_BIN). See each package's README.md and integration/CONTRACT.md for the exact CLI contract.

Quick Start

# 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

Commands

Architecture

                    ┌─────────────────┐
                    │  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 Escapes

Payload lines starting with + have the + prefix consumed as a sigil marker. To produce a literal leading + or -, use the escapes:

A blank line inside a payload block is written as a bare empty line (no + prefix):

INS.POST 2:
+First paragraph.

+Second paragraph.

Limitations

FAQ

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.