HashPilot — Deterministic Structured Editing for AI Coding Agents

The Problem

AI agents edit code blind

No IDE, no visual location, no working memory of file structure. Yet tools expect agents to edit like humans — counting lines and guessing text.

Line Counting

"Replace line 42" breaks when one import shifts every line. +3 retries, corrupted file.

Fuzzy Find-Replace

Guess the right text to match — or match the wrong occurrence. Silent corruption, wasted tokens.

Race Conditions

Two edits interleave. Invalid syntax, agent confusion, no recovery.

The Solution

Cryptographic certainty for every edit

🔐

SHA-256 Anchors

Target content by its cryptographic fingerprint. If the hash matches, you're editing the right content. No ambiguity.

For agents — never edit the wrong content

⚡

3-Tier Routing

AST → Hash → Diff. Auto-selects the best strategy per file + operation. One command, right tool every time.

For agents — one shot, every time

🔄

Stale Recovery

Detects out-of-date edits (file changed since read) and re-applies transparently. No silent corruption.

For agents — survive race conditions

🎯

Intents (M5)

"Add a parameter to processData" → discovers all call sites, plans the edit, executes every step.

For agents — multi-file refactors in one shot

✅

Verification Bundling

Run formatter + linter + typechecker + tests in one command. Optional revert on failure.

For developers — know it works

📋

Provenance

provenance query src/utils.ts shows edit history per line. Like git blame for agent edits.

For teams — audit trail for AI changes

Who It's For

Three audiences, one tool

👤

Developers

Edits work on the first try
Every change is auditable
Trust AI refactors completely
It's invisible — agent uses it automatically

🤖

AI Agents

SHA-256 hash = no ambiguity
Less re-reading = fewer round-trips
AST edits are structurally valid
Intents handle the blast radius
Telemetry monitors reliability

🏢

Engineering Teams

Provenance = compliance
Team-wide config policies
Batch edits at scale
Verify = confidence before merge

Quick Start

Install in one command

curl -fsSL https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/install.sh | sh

Requires Bun 1.2+ — installs CLI, configures Claude Code, OpenCode, and Pi adapters automatically.

Your First Edit

# 1. Read a file — get its content hash
structured-edit read-many src/main.ts

# 2. Edit by hash — target the exact content
HASH="abc123..."  # from read-many output
structured-edit replace-hash src/main.ts "$HASH" "  port: 8080" --range 5:5

# 3. Verify nothing broke
structured-edit verify-changes src/main.ts --auto-detect

Architecture

The 3-tier routing model

┌─────────────────┐ │ Your Edit │ └────────┬────────┘ │ ▼ ┌──────────────────────────┐ │ 1. AST Route │ ◄── tree-sitter syntax edits │ TS/TSX/JS/Python/Go/Rust│ rename-symbol, replace-body └────────────┬─────────────┘ │ unsupported ▼ ┌──────────────────────────┐ │ 2. Hash Route │ ◄── SHA-256 anchored replacement │ (any file) │ stale-anchor detection └────────────┬─────────────┘ │ no hash ▼ ┌──────────────────────────┐ │ 3. Diff Route │ ◄── LCS-based search-and-replace │ (fallback) │ fuzzy matching └──────────────────────────┘

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

Commands

Everything at your fingertips

Read & Search

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

Edit — Hash Route

Command	What It Does
replace-hash <file> <hash> <content>	SHA-256 anchored replacement with stale recovery

Edit — AST Route

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

Multi-File & Verification

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.

Integrations

Works with every major agent

Claude Code

HashPilot section injected into ~/.claude/CLAUDE.md. Claude uses structured-edit commands as shell tools.

OpenCode

Skill at ~/.config/opencode/skills/hashpilot/ + subagent for delegated editing.

Pi

Native extension with 7 custom tools + /hp slash command.

All adapters follow the Adapter Contract — a machine-readable JSON protocol any agent can consume.

Development

Build from source

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.