AI agents edit code blind. HashPilot gives them cryptographic certainty. Every edit anchored by SHA-256 hash — not a line number or fuzzy text match.
PositioningHashPilot is the safe, verifiable, observable file-editing primitive for coding agents. While other tools match text or rewrite whole files, HashPilot anchors every edit to a cryptographic digest — if the hash doesn't match, nothing changes. With AST-native editing, provenance trails, and a verify pipeline, it gives agents deterministic control over how code changes land on disk.
The only position no competitor occupies: hash-anchored + AST-aware + provenance-tracked. See COMPETITIVE-ANALYSIS.md →
No IDE, no visual location, no working memory of file structure. Yet tools expect agents to edit like humans — counting lines and guessing text.
"Replace line 42" breaks when one import shifts every line. +3 retries, corrupted file.
Guess the right text to match — or match the wrong occurrence. Silent corruption, wasted tokens.
Two edits interleave. Invalid syntax, agent confusion, no recovery.
Target content by its cryptographic fingerprint. If the hash matches, you're editing the right content. No ambiguity.
AST → Hash → Diff. Auto-selects the best strategy per file + operation. One command, right tool every time.
Detects out-of-date edits (file changed since read) and re-applies transparently. No silent corruption.
"Add a parameter to processData" → discovers all call sites, plans the edit, executes every step.
Run formatter + linter + typechecker + tests in one command. Optional revert on failure.
provenance query src/utils.ts shows edit history per line. Like git blame for agent edits.
curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | bash
Each agent gets its own adapter. Read the instructions to install HashPilot:
Adds HashPilot commands to ~/.claude/CLAUDE.md
Skill + subagent at ~/.config/opencode/
Extension + /hp slash command
# 1. Read a file — get its content hash
hashpilot read-many src/main.ts
# 2. Edit by hash — target the exact content
HASH="abc123..." # from read-many output
hashpilot replace-hash src/main.ts "$HASH" " port: 8080" --range 5:5
# 3. Verify nothing broke
hashpilot verify-changes src/main.ts --auto-detectThe router auto-selects. route-edit tries AST → Hash → Diff. Every route records telemetry and provenance.
Deep dive: design doc → — module internals, data flow, key decisions, error handling.
| Command | What It Does |
|---|---|
| read-many <files> | Batch read with SHA-256 content hashes |
| read-hash <file> <line> | Read a specific line with context hash |
| grep-many <pattern> <paths> | Regex search across files |
| symbol-lookup-many <paths> | Find symbol definitions by name |
| Command | What It Does |
|---|---|
| replace-hash <file> <hash> <content> | SHA-256 anchored replacement with stale recovery |
| Command | What It Does |
|---|---|
| ast find-symbols <file> | List all symbols in a file |
| ast rename-symbol <file> <old> <new> | Rename symbol + all references |
| ast replace-body <file> <symbol> <body> | Replace a function/method body |
| ast add-import <file> <spec> | Add an import with grouped merging |
| ast remove-import <file> <spec> | Remove an import statement |
| ast insert-before/after | Insert content around a symbol |
| Command | What It Does |
|---|---|
| route-edit <file> <op> | Auto-routed edit: AST → Hash → Diff |
| batch <op> <files> | Same edit on many files, parallel or serial |
| intent <json> | Declarative multi-file plan + execute |
| verify-changes <files> | Formatter + linter + typechecker + tests |
| provenance query <file> | Edit history (git blame for agents) |
| telemetry health | Health report with threshold warnings |
All commands accept --actor, --task-id, --reason for provenance. Every command outputs structured JSON.
HashPilot section injected into ~/.claude/CLAUDE.md. Claude uses hashpilot commands as shell tools.
Skill at ~/.config/opencode/skills/hashpilot/ + subagent for delegated editing.
Native extension with 7 custom tools + /hp slash command.
All adapters follow the Adapter Contract — a machine-readable JSON protocol any agent can consume.
git clone https://github.com/bigknoxy/HashPilot.git
cd HashPilot
bun install
bun test # 344 tests, 96.68% line coverage
bun run build # Build CLI to dist/
bun test tests/hash-edit.test.ts # Single file
bun test -t "test name" # Filter by name
Configuration: layered (env var → CLI flag → .hashpilot.json → global → defaults).
Route policies per language, per operation. Telemetry opt-out.