hash-edit (Python)

Line-hash anchored read/edit/write for AI coding agents — windowed reads, strict version checks, atomic writes.

Install

pip install hash-edit
# or
uv add hash-edit

Quick start

from hash_edit import HashEditHarness

h = HashEditHarness("/path/to/project")

# 1. Read — returns rendered lines with hashes and a full-file version digest
result = h.read("src/app.py")
# result["version"]  == "4a3f..."
# result["lines"]    == ["1:ab|import os", "2:cd|", "3:ef|def main(): ..."]
# result["total_lines"] == 3

# 2. Edit — anchored ops verified against expected_version
h.edit(
    "src/app.py",
    [
        {"op": "replace", "line": 3, "hash": "ef", "lines": ["def main():", "    pass"]},
    ],
    expected_version=result["version"],
)

# 3. Write — safely create or overwrite; expected_version required when overwriting
h.write("src/new_file.py", "# new content\n")

Windowed reads

For large files, pass start_line / end_line to read only the lines you need (saves 55–87% tokens):

result = h.read("src/app.py", start_line=100, end_line=150)
# result["lines"]       — 51 rendered lines, numbered 100–150
# result["total_lines"] — full file length (e.g. 1 200)
# result["version"]     — full-file digest, same as a whole-file read

The version is always the full-file blake2s digest, so a windowed read still gives you a valid expected_version to pass to edit().

Error classes

All six inherit from HashEditError.

Further reading

• Root README — project overview, TypeScript package, and benchmarks
• docs/spec.md — full protocol specification
• docs/INTERFACE_DESIGN.md — design rationale