@levnikolaevich/hex-line-mcp 1.3.1 → 1.3.3

package/README.md

@@ -13,17 +13,34 @@ Every line carries an FNV-1a content hash. Every edit must present those hashes
 
 ### 11 MCP Tools
 
+Core day-to-day tools:
+
+- `read_file`
+- `edit_file`
+- `grep_search`
+- `outline`
+- `verify`
+- `bulk_replace`
+
+Advanced / occasional:
+
+- `write_file`
+- `directory_tree`
+- `get_file_info`
+- `changes`
+- `setup_hooks`
+
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
-| `read_file` | Read file with hash-annotated lines and range checksums | Partial reads via `offset`/`limit` |
-| `edit_file` | Hash-verified edits with anchor or text replacement | Returns compact diff via `diff` package |
+| `read_file` | Read file with hash-annotated lines, checksums, and revision | Partial reads via `offset`/`limit` |
+| `edit_file` | Revision-aware anchor edits (`set_line`, `replace_lines`, `insert_after`, `replace_between`) | Batched same-file edits + conservative auto-rebase |
 | `write_file` | Create new file or overwrite, auto-creates parent dirs | Path validation, no hash overhead |
 | `grep_search` | Search with ripgrep, 3 output modes, per-group checksums | Edit-ready: grep -> edit directly with checksums |
 | `outline` | AST-based structural overview via tree-sitter WASM | 95% token reduction (10 lines instead of 500) |
-| `verify` | Check if held range checksums are still valid | Single-line response avoids full re-read |
+| `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
 | `directory_tree` | Compact directory tree with root .gitignore support | Skips node_modules/.git, shows file sizes |
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
-| `setup_hooks` | Configure PreToolUse + PostToolUse hooks for Claude/Gemini/Codex | One call sets up everything, idempotent |
+| `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
 | `bulk_replace` | Search-and-replace across multiple files by glob | Per-file diffs, dry_run, max_files safety |
 
@@ -33,13 +50,13 @@ Every line carries an FNV-1a content hash. Every edit must present those hashes
 |-------|---------|--------|
 | **PreToolUse** | Read/Edit/Write/Grep on text files | Blocks built-in, forces hex-line tools |
 | **PreToolUse** | Bash with dangerous commands | Blocks `rm -rf /`, `git push --force`, etc. Agent must confirm with user |
-| **PostToolUse** | Bash with 50+ lines output | RTK: deduplicates, truncates, summarizes |
+| **PostToolUse** | Bash with 50+ lines output | RTK: deduplicates, truncates, shows filtered summary to Claude as feedback |
 | **SessionStart** | Session begins | Injects full tool preference list into agent context |
 
 
 ### Bash Redirects
 
-PreToolUse also intercepts simple Bash commands: cat, head, tail, ls, tree, find, stat, wc -l, grep, rg, sed -i, diff — redirects to hex-line equivalents. Compound commands with pipes are allowed.
+PreToolUse also intercepts simple Bash commands: cat, head, tail, tree, find, stat, wc -l, grep, rg, sed -i — redirects to hex-line equivalents. `ls`/`dir` only redirected for recursive listing (`ls -R`, `dir /s`); simple `ls path` is allowed. Compound commands with pipes are allowed.
 ## Install
 
 ### MCP Server
@@ -49,6 +66,8 @@ npm i -g @levnikolaevich/hex-line-mcp
 claude mcp add -s user hex-line -- hex-line-mcp
 ```
 
+ripgrep is bundled via `@vscode/ripgrep` — no manual install needed for `grep_search`.
+
 ### Hooks
 
 Automatic setup (run once after MCP install):
@@ -69,41 +88,83 @@ mcp__hex-line__setup_hooks(agent="claude")
 
 The `setup_hooks` tool automatically installs the output style to `~/.claude/output-styles/hex-line.md` and activates it if no other style is set. To activate manually: `/config` > Output style > hex-line.
 
-## Token Efficiency
-
-Benchmark v3 (21 code files, 4,801 lines, 18 scenarios):
-
-| # | Scenario | Baseline | Hex-line | Savings | Ops | Steps |
-|---|----------|----------|----------|---------|-----|-------|
-| 1 | Read full (<50L) | 1,837 ch | 1,676 ch | 9% | 1→1 | 1→1 |
-| 1 | Read full (50-200L) | 4,976 ch | 4,609 ch | 7% | 1→1 | 1→1 |
-| 1 | Read full (200-500L) | 11,702 ch | 10,796 ch | 8% | 1→1 | 1→1 |
-| 1 | Read full (500L+) | 76,079 ch | 71,578 ch | 6% | 1→1 | 1→1 |
-| 2 | Outline+read (200-500L) | 11,702 ch | 3,620 ch | **69%** | 1→2 | 1→2 |
-| 2 | Outline+read (500L+) | 76,079 ch | 19,020 ch | **75%** | 1→2 | 1→2 |
-| 3 | Grep search | 2,816 ch | 2,926 ch | -4% | 1→1 | 1→1 |
-| 4 | Directory tree | 1,967 ch | 699 ch | **64%** | 1→1 | 1→1 |
-| 5 | File info | 371 ch | 197 ch | **47%** | 1→1 | 1→1 |
-| 6 | Create file (200L) | 113 ch | 85 ch | **25%** | 1→1 | 1→1 |
-| 7 | Edit x5 sequential | 2,581 ch | 1,529 ch | **41%** | 5→5 | 5→5 |
-| 8 | Verify checksums (4 ranges) | 8,295 ch | 93 ch | **99%** | 4→1 | 4→1 |
-| 9 | Multi-file read (2 files) | 3,674 ch | 3,358 ch | 9% | 2→1 | 1→1 |
-| 10 | bulk_replace dry_run (5 files) | 2,795 ch | 1,706 ch | **39%** | 5→1 | 5→1 |
-| 11 | Changes (semantic diff) | 830 ch | 271 ch | **67%** | 1→1 | 1→1 |
-| 12 | FILE_NOT_FOUND recovery | 2,071 ch | 101 ch | **95%** | 3→1 | 3→1 |
-| 13 | Hash mismatch recovery | 8,918 ch | 423 ch | **95%** | 3→1 | 3→1 |
-| 14 | Bash redirects (cat+ls+stat) | 5,602 ch | 4,695 ch | **16%** | 3→3 | 1→1 |
-| 15 | HASH_HINT multi-match recovery | 8,888 ch | 653 ch | **93%** | 3→2 | 3→1 |
-
-**Average savings: 45% (flat) / 52% (weighted) | 39→28 ops (28% fewer) | 36→25 steps.**
-
-Reproduce: `node benchmark.mjs` or `node benchmark.mjs --with-graph --repo /path/to/repo`
+## Benchmarking
+
+`hex-line-mcp` now distinguishes:
+
+- `tests` — correctness and regression safety
+- `benchmarks` — comparative workflow efficiency against built-in tools
+- `diagnostics` — modeled tool-level measurements for engineering inspection
+
+Public benchmark mode reports only comparative multi-step workflows:
+
+```bash
+npm run benchmark -- --repo /path/to/repo
+```
+
+Optional diagnostics stay available separately:
+
+```bash
+npm run benchmark:diagnostic -- --repo /path/to/repo
+npm run benchmark:diagnostic:graph -- --repo /path/to/repo
+```
+
+The diagnostics output includes synthetic tool-level comparisons such as read, grep, verify, and graph-enrichment helpers. Those numbers are useful for inspecting output shape and token behavior, but they are not the public workflow benchmark score.
+
+Current sample run on the `hex-line-mcp` repo with session-derived workflows:
+
+| ID | Workflow | Built-in | hex-line | Savings | Ops |
+|----|----------|---------:|---------:|--------:|----:|
+| W1 | Debug hook file-listing redirect | 23,143 chars | 882 chars | 96% | 3→2 |
+| W2 | Adjust `setup_hooks` guidance and verify | 24,877 chars | 1,637 chars | 93% | 3→3 |
+| W3 | Repo-wide benchmark wording refresh | 137,796 chars | 38,918 chars | 72% | 15→1 |
+| W4 | Inspect large smoke test before edit | 49,566 chars | 2,104 chars | 96% | 3→3 |
+
+Workflow summary: `89%` average token savings, `24→9` tool calls (`63%` fewer).
+
+These workflows are derived from recent real Claude sessions, but executed against local reproducible fixtures in the repository. They should be read as workflow-efficiency measurements, not as correctness or semantic-quality claims.
+
+### Optional Graph Enrichment
+
+If a project already has `.codegraph/index.db`, `hex-line` can add lightweight graph hints to `read_file`, `outline`, `grep_search`, and `edit_file`.
+
+- Graph enrichment is optional. If `.codegraph/index.db` is missing, `hex-line` falls back to standard behavior silently.
+- `better-sqlite3` is optional. If it is unavailable, `hex-line` still works without graph hints.
+- `edit_file` reports **Call impact**, not full semantic blast radius. The warning uses call-graph callers only.
+
+`hex-line` does not read `hex-graph` internals directly anymore. The integration uses a small read-only contract exposed by `hex-graph-mcp`:
+
+- `hex_line_contract`
+- `hex_line_symbol_annotations`
+- `hex_line_call_edges`
 
 ## Tools Reference
 
+## Common Workflows
+
+### Local code edit in one file
+
+1. `outline` for large code files
+2. `read_file` for the exact range you need
+3. `edit_file` with all known hunks in one call
+
+### Follow-up edit on the same file
+
+1. Carry `revision` from the earlier `read_file` or `edit_file`
+2. Pass it back as `base_revision`
+3. Use `verify` before rereading the file
+
+### Rewrite a long block
+
+Use `replace_between` inside `edit_file` when you know stable start/end anchors and want to replace a large function, class, or config block without reciting the old body.
+
+### Literal rename / refactor
+
+Use `bulk_replace` for text rename patterns across one or more files. Do not use it as a substitute for structured block rewrites.
+
 ### read_file
 
-Read a file with FNV-1a hash-annotated lines and range checksums. Supports directory listing.
+Read a file with FNV-1a hash-annotated lines, range checksums, file checksum, and revision. Supports directory listing.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -120,11 +181,13 @@ ab.1    import { resolve } from "node:path";
 cd.2    import { readFileSync } from "node:fs";
 ...
 checksum: 1-50:f7e2a1b0
+revision: rev-12-a1b2c3d4
+file: 1-120:beefcafe
 ```
 
 ### edit_file
 
-Edit using hash-verified anchors or text replacement. Returns diff + post-edit checksums for chaining edits.
+Edit using revision-aware hash-verified anchors. Prefer one batched call per file. For text rename use bulk_replace.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -132,19 +195,28 @@ Edit using hash-verified anchors or text replacement. Returns diff + post-edit c
 | `edits` | string | yes | JSON array of edit operations (see below) |
 | `dry_run` | boolean | no | Preview changes without writing |
 | `restore_indent` | boolean | no | Auto-fix indentation to match anchor context (default: false) |
+| `base_revision` | string | no | Prior revision from `read_file` / `edit_file` for same-file follow-up edits |
+| `conflict_policy` | enum | no | `conservative` or `strict` (default: `conservative`) |
 
 Edit operations (JSON array):
 
 ```json
 [
   {"set_line": {"anchor": "ab.12", "new_text": "replacement line"}},
-  {"replace_lines": {"start_anchor": "ab.10", "end_anchor": "cd.15", "new_text": "..."}},
+  {"replace_lines": {"start_anchor": "ab.10", "end_anchor": "cd.15", "new_text": "...", "range_checksum": "10-15:a1b2c3d4"}},
   {"insert_after": {"anchor": "ab.20", "text": "inserted line"}},
-  {"replace": {"old_text": "unique text", "new_text": "replacement"}},
-  {"replace": {"old_text": "find all", "new_text": "replace all", "all": true}}
+  {"replace_between": {"start_anchor": "ab.30", "end_anchor": "cd.80", "new_text": "...", "boundary_mode": "inclusive"}}
 ]
 ```
 
+Result footer includes:
+
+- `status: OK | AUTO_REBASED | CONFLICT`
+- `revision: ...`
+- `file: ...`
+- `changed_ranges: ...` when relevant
+- `retry_checksum: ...` on local conflicts
+
 ### write_file
 
 Create a new file or overwrite an existing one. Creates parent directories automatically.
@@ -192,12 +264,13 @@ Not for `.md`, `.json`, `.yaml`, `.txt` -- use `read_file` directly for those.
 
 ### verify
 
-Check if range checksums from a prior read are still valid.
+Check if range checksums from a prior read are still valid, optionally relative to a prior `base_revision`.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | yes | File path |
 | `checksums` | string | yes | JSON array of checksum strings, e.g. `["1-50:f7e2a1b0"]` |
+| `base_revision` | string | no | Prior revision to compare against latest state |
 
 Returns a single-line confirmation or lists changed ranges.
 
@@ -269,7 +342,7 @@ hex-line-mcp/
   lib/
     hash.mjs          FNV-1a hashing, 2-char tags, range checksums
     read.mjs          File reading with hash annotation
-    edit.mjs          Anchor-based and text-based edits, diff output
+    edit.mjs          Anchor-based edits, diff output
     search.mjs        ripgrep wrapper with hash-annotated results
     outline.mjs       tree-sitter WASM AST outline
     verify.mjs        Range checksum verification
@@ -277,9 +350,9 @@ hex-line-mcp/
     tree.mjs          Directory tree with .gitignore support
     changes.mjs       Semantic git diff via AST
     bulk-replace.mjs  Multi-file search-and-replace
-    setup.mjs         Hook installation for Claude/Gemini/Codex
+    setup.mjs         Claude hook installation + output style setup
     format.mjs        Output formatting utilities
-    coerce.mjs        Parameter alias mapping
+    coerce.mjs        Parameter pass-through (identity)
     security.mjs      Path validation, binary detection, size limits
     normalize.mjs     Output normalization, deduplication, truncation
 ```
@@ -317,7 +390,7 @@ FNV-1a accumulator over all line hashes in the range (little-endian byte feed).
 <details>
 <summary><b>Does it work without Claude Code?</b></summary>
 
-Yes. hex-line-mcp is a standard MCP server (stdio transport). It works with any MCP-compatible client -- Claude Code, Gemini CLI, Codex CLI, or custom integrations. Hooks are Claude/Gemini/Codex-specific.
+Yes. hex-line-mcp is a standard MCP server (stdio transport). It works with any MCP-compatible client -- Claude Code, Gemini CLI, Codex CLI, or custom integrations. Hook installation is Claude-specific; Gemini/Codex use MCP Tool Preferences guidance instead.
 
 </details>
 
@@ -336,9 +409,9 @@ Outline works on code files only (15+ languages via tree-sitter WASM). For markd
 </details>
 
 <details>
-<summary><b>How does the RTK filter reduce tokens?</b></summary>
+<summary><b>How does the RTK filter work?</b></summary>
 
-The PostToolUse hook normalizes Bash output (replaces UUIDs, timestamps, IPs with placeholders), deduplicates identical lines, and truncates to first 15 + last 15 lines. Average savings: 45% (flat) / 52% (weighted) across 18 benchmark scenarios.
+The PostToolUse hook normalizes Bash output (replaces UUIDs, timestamps, IPs with placeholders), deduplicates identical lines, and truncates to first 15 + last 15 lines. The filtered summary is shown to Claude as stderr feedback via exit code 2.
 
 </details>