Hash-verified file editing MCP + token efficiency hook for AI coding agents
Every time an AI agent reads a file, edits a line, or checks if something changed, it burns tokens. Built-in tools return full file contents, repeat unchanged data, and offer no way to verify that an edit targets the right lines. We built hex-line-mcp to fix this.
hex-line-mcp is an MCP server that adds FNV-1a content hashes to every line of every file your agent reads. When the agent edits, it must present those hashes back — proving it's editing what it thinks it's editing. No stale context, no silent corruption.
Real-world workflows where hex-line changes the game.
Your agent needs to patch one function in a 600-line file. With built-in Read, it dumps all 600 lines into context — 76K characters. With hex-line, it runs outline first: tree-sitter parses the AST and returns the file structure in ~10 lines. The agent spots the function, reads just those 30 lines.
The agent edited a file 5 minutes ago and wants to make another change. It still holds the range checksums from the first read. Instead of re-reading 4 file ranges (8,295 characters total), it calls verify — one request, one line back: "all valid" or "range 3 changed."
The agent tries to edit line 42, but someone (or another agent) modified the file since the last read. Built-in tools? Silent overwrite — the bug is now in production. hex-line rejects the edit, shows exactly which lines changed, and includes a hash hint so the agent fixes it in one retry instead of three round-trips.
Five files need oldName replaced with newName. Built-in approach: open each file, find-and-replace, save — 5 separate edit calls. hex-line bulk_replace: one call with an explicit root path plus a glob pattern, dry-run preview, then apply. In normal use the agent auto-fills that scope from the current project. Per-file diffs returned.
Agent misremembers a filename. Built-in: read fails → agent guesses → tries another name → reads. Three calls, 2,071 characters. hex-line: read fails, but the error includes the parent directory listing. Agent picks the right file in one retry.
Everything an agent needs to read, edit, search, and understand code.
| Tool | What it does |
|---|---|
| read_file | Hash-annotated lines + range checksums. Batch mode for multiple files |
| edit_file | Hash-verified anchor edits (set_line, replace_lines, insert_after). Returns compact diff |
| write_file | Create or overwrite. Auto-creates parent directories |
| grep_search | ripgrep with hash-annotated matches — search, then edit directly |
| outline | AST structural overview via tree-sitter for JavaScript/TypeScript, Python, C#, PHP, and markdown headings. 95% token reduction vs full read |
| verify | Check if held checksums are still valid. Single-line response |
| inspect_path | Unified file-or-directory inspection: file metadata for files, tree or pattern search for directories |
| changes | Semantic diff against git ref with graph-backed local review when a code graph is present |
| bulk_replace | Search-and-replace across files by glob inside an explicit root path. Dry-run mode |
hex-line ships with a hook system that works alongside the MCP tools:
PreToolUse — hard-redirects project-scoped text Read/Edit/Write/Grep to hex-line, redirects project file-inspection Bash commands, and blocks dangerous Bash commands (git push --force, rm -rf /, DROP) until the user confirms.
PostToolUse — filters verbose Bash output (50+ lines): deduplicates, normalizes, truncates. Keeps first 15 + last 15 lines.
SessionStart — injects a short bootstrap hint at session start. If the hex-line output style is already active, the hook stays minimal and defers to that style.
Bash redirects — intercepts project-scoped file inspection commands such as cat, type, Get-Content, ls, dir, tree, find, Get-ChildItem, grep, rg, findstr, Select-String, stat, Get-Item, and sed -i. Targeted inspection pipelines are redirected; Git/build/test/docker/network workflows remain allowed.
A persistent Output Style installed to
~/.claude/output-styles/hex-line.md embeds tool preferences directly in Claude's system prompt — reducing hook firings by making Claude prefer hex-line tools from the start. It is auto-synced on MCP server startup alongside Claude hooks; Codex uses the same preferences as manual guidance. The steering layer tells the agent to auto-fill file paths for file tools and the current project root for repo-wide tools, so scope stays explicit without making the user type it manually.
hex-line-mcp is validated with smoke tests, lint/check gates, and internal scenario fixtures. Comparative built-in vs hex-line benchmarks live outside this package.
Commands
npm test
npm run lint
npm run check
Maintainers can also run the internal scenario harness for reproducible repo-local workflow regressions.
npm run scenarios -- --repo /path/to/repo
npm run scenarios:diagnostic -- --repo /path/to/repo