dsh-hashline-edittool

dsh-hashline-edittool

Line-anchored edit tool for DeepSeek Harness

Powered by <line>#<hash> positioning — chained edits skip the re-read, fewer tokens, more context space for real work.

English · 简体中文

Quick Start • Why Hashline • Benchmark • Tools • Acknowledgments

Forked from Rianico/dsh-better-edit — maintained independently from here on.

---

"The harness — not the model — is the bottleneck." — Can Bölük, The Harness Problem

Most edit tools ask the model to echo the old code token-for-token before it can change anything — and that's exactly where agents fail: 46–51% patch-format failure rates for several models with replace-style edits. dsh-hashline-edittool goes deeper. Every line of a file gets a unique # marker (absolute line number + 3-char content hash), and edits target those markers. The old text is never echoed, the hash half survives edits above, and every resolved range is verified against exactly what the model saw — wrong-line edits cannot silently land, and the post-edit Shift: block lets the model chain the next edit without a re-read.

Why you need this

str_replace makes the model re-type the code it's replacing — pure transcription cost (output tokens, billed ~5-6× input), and where agents fail most: 46–51% patch failures on real models, worse on bigger blocks, each failure costing a re-read and a retry.

Hashline sends two # anchors instead of the old text — 26% fewer edit tokens (24–45% on multi-line ranges) — and verifies every range against what the model saw: an edit lands where you meant, or fails loudly with fresh anchors. Anchors are content addresses that survive edits above; chained edits skip the re-read by reading the post-edit Shift: block — and a leaner context keeps the model's attention on the code, not on re-transcribing it.

Not for one-line touch-ups (near parity) or new files (write). It pays off in long sessions and structural edits — anywhere an edit must not land on the wrong line.

Quick Start

Install

npx @deepseek-ai/dsh plugin --profile web add github:hyperion2144/dsh-hashline-edittool   # from github
npx @deepseek-ai/dsh plugin --profile web add dsh-hashline-edittool   # from npm
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-hashline-edittool   # from a local checkout

The profile's next session runs with the hashline tools installed. To verify the layer is active:

dsh --profile  --dump-config   # shows a "# == dsh-hashline-edittool" layer

Requirement
Node	^22.19.0 || >=24.0.0 (dsh's requirement; the store uses node:sqlite)
Profile	a dsh profile (dsh plugin initializes one on first use)
Backends	sandboxed / remote filesystems supported (writes go through ctx.fs)

read returns every line as #│ — the absolute line number (1-indexed) plus a 3-char content-derived hash. The response opens with a HASH IDENTIFIER │ FILE LINES header that separates the marker column from the verbatim file content:

HASH IDENTIFIER │ FILE LINES
 3#ve7│function hello() {
 4#szJ│  console.log("world");
 5#kQm│}

edit targets one or more ranges of line#hash anchors via an edits:[] array, each with an op semantic (ins / del / replace). A single-line replace:

{
  "path": "src/main.ts",
  "edits": [
    { "op": "replace", "from": "4#szJ", "lines": ["  console.log('hi');"] }
  ]
}

and produces a diff with fresh anchors plus a Shift: block that describes how absolute line numbers below the edit moved — the next edit chains from there without a re-read:

HASH IDENTIFIER │ FILE LINES
+ 4#a3m│  console.log('hi');
- 4#szJ│  console.log("world");

Shift: lines > 5 shift by +1. Use newLine=5#kQm to edit the next row without re-reading.

Configuring Guidance per Preset

The tool:read / tool:edit / tool:undo_last_edit / tool:grep guidance sections are plain-markdown files, overridable per agent preset. Override files live in the plugin's shared home — never the workspace store:

$DSH_HOME/plugins/dsh-hashline-edittool/
/.md

(default home ~/.dsh, so ~/.dsh/plugins/dsh-hashline-edittool/). The section table:

File	Section	Default order
read.md	tool:read	130
edit.md	tool:edit	131

| undo_last_edit.md | tool:undo_last_edit | 132 |

On first boot the plugin seeds the four shipped presets — standard/, code/, minimal/, cordis/ — each with the compiled guidance as editable files (plus order front-matter), so every preset's guidance starts editable rather than blank. A README.md at the plugin-home root documents the scheme. Files are seeded once and never rewritten, so your edits survive — a reset is the one exception (see Reset / restore defaults below). A preset directory may hold only the sections you want to override — the rest fall through to the compiled defaults.

A file is pure prose unless it opens with an order front-matter fence, which moves the section in the assembled system prompt:

---
order: 150
---

Per section, resolution reads /.md, else the compiled default. Files are read once per agent at session-start, so edits apply to new sessions — never mid-session. A preset with no seeded directory (e.g. a user-authored one) falls back to the compiled defaults unless you copy a seeded dir to its name. A deployment without the agentPresets service (no preset roster) keeps the compiled defaults and never touches these files; presets are never required.

Reset / restore defaults

Emptying or deleting an override file restores that section's compiled default guidance and order: the default renders at session-start, and the file re-seeds at next boot.

• Reset = delete the file, or empty it AND remove the front-matter fence. A whitespace-only file with no fence means "I want the default" — the compiled default renders, and the file re-seeds at next boot for any preset dir, shipped or custom.
• Blank on purpose = keep a valid fence. Any well-formed --- fence — even a keyless ---\n---\n, even an empty body — is a deliberate-intent signal: the file is explicit content and is never reset or re-seeded.
• Broken fence = fast fail. A --- fence that does not parse (missing closing ---, non-integer order, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
• Shipped vs custom. Shipped preset files (standard, code, minimal, cordis) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole / directory re-seeds all four section files at boot (shipped presets).
• Reset restores the current bundle defaults — a plugin upgrade yields new defaults.

Re-seeding happens at boot, never mid-session.

Why Hashline

Token-saving. An edit call carries remove_from / remove_to (two # markers) plus the replacement text — it never echoes the text being replaced. A str_replace call must reproduce that text verbatim. On a 12-edit session over a realistic file this is 26% fewer output tokens (24–45% on multi-line ranges) — and these are output tokens, billed at ~5-6× the input rate. See the benchmark.

But this was never about “fewest tokens.” Savings scale with the replaced text — near parity on the shortest one-line touch-ups — and a compact patch language like @oh-my-pi/hashline can emit a lighter payload still (42–53% on the same session). The point is the right kind of edit call: no re-typing old code, and nothing for the model to track except two stable content addresses (the hash half stays the same across edits; the line half shifts in the Shift: block, with newLine#oldHash for the next anchor).

Correctness. Every resolved edit range is verified against the exact lines the model was shown. A stale, never-served, or ambiguous range is hard-rejected before anything is written, and the current range is echoed back as fresh anchors (reject-and-serve) — the retry needs no read.

A modern edit pattern for agents. Content-addressed anchors (the 3-char hash) survive edits above; the line#hash form additionally pins the line's absolute position. Edit one part of a file and the rest of the line#hash markers shift predictably — the post-edit response carries a Shift: block (lines > N shift by +K) that lets the model chain the next edit via newLine#oldHash without a re-read.

How It Compares

	hashline edit	str_replace (Claude Code / Codex)	@oh-my-pi/hashline patch
Replaced text never echoed in the call	✅ 2 hashes only	❌ verbatim	✅ + rows only
Lines addressed by	line number + content hash	text match	number + file-content tag
Verified against what the model saw	✅ every line	❌ first match wins	~ file version only
Stale file detected	✅ rejects, fresh anchors	❌ may match wrong spot	✅ tag mismatch → refuse or 3-way merge
Anchors survive edits above	✅ content-addressed (hash) + Shift block (line)	✅ content-based	❌ renumber + new tag
Chained edits without re-reads	✅ Shift block + newLine#oldHash	~	~ via edit-response numbers
Unambiguous when text repeats	✅ boundary anchors verified	❌ first occurrence	~ position, unverified per line
Wrong-line edit never lands silently	✅ every line verified	❌ first match wins	~ possible in principle (tag checks version, not lines)
Block ops / registers / MV / REM	❌	❌	✅
One document per change	❌ per-edit call	❌ per-edit call	✅ multi-hunk patch
Runtime	✅ Node (dsh)	—	⚠️ Bun only
Undo	✅ persisted	❌	❌ not in scope

~ = occasionally / inconsistently. @oh-my-pi/hashline is a compact line-anchored patch language (npm, repo): [path#tag] headers bind each hunk to a full-file content hash, PUT N.=M: addresses lines by number, and every edit renumbers — take the next numbers and tag from the edit response or a fresh read.

Different jobs, same lineage. Both descend from the harness-problem insight that the model should never re-type old code. @oh-my-pi/hashline is a patch-language library — payload-light (42% saved per edit, 53% in a single batch document, see benchmark), with syntactic block ops (PUT N*:), registers, REM/MV, multi-hunk documents, a pluggable filesystem for any backend, and session-aware 3-way-merge recovery on stale tags. This plugin is a dsh tool pair: read hands the model 3-char content hashes, edit takes two of them, and every resolved line is verified against the served state — no line numbers to renumber, no tag to re-fetch, a wrong anchor can never land on the wrong line, and undo_last_edit survives restarts. Its trade-offs: a JSON envelope per edit costs a little payload, there are no block ops, and it lives inside dsh (Node) rather than as a standalone patcher (Bun). Pick hashline-the-library for a cross-backend patch format; pick hashline-the-tool for verified, content-addressed edits in your agent.

Correctness in edge cases

The token benchmark measures the payload the model emits — it assumes the model gets every address right, for free. Correctness is where the two hashline implementations actually diverge. These are the real failure modes from the harness-problem literature (wrong-line edits, drift, repeated text), and what each tool does when they hit:

Edge case	hashline edit (this plugin)	@oh-my-pi/hashline patch
Wrong address (off-by-one anchor / line number)	Impossible — anchors resolve to specific lines; every resolved line is verified against served state, rejected before anything is written	Possible — a wrong line number against a current tag applies silently at the wrong place; the tag proves the file version, never the lines
File changed on disk after the model's view	Hard reject + fresh anchors echoed (reject-and-serve); retry needs no read	Tag mismatch → refuse or best-effort 3-way merge onto unknown current content
An edit above shifts the file	Nothing shifts — anchors are content addresses; the diff serves fresh anchors	Every edit renumbers — “RE-GROUND AFTER EVERY EDIT” is the format's own #1 rule; the model carries the bookkeeping
Repeated / identical text	Per-line hashes are unique (collision-resolved); ambiguity → [E_AMBIGUOUS_ANCHOR]	Position-based, so repeats don't confuse it — but the position itself is unverified
Lines never shown to the model	[E_RANGE_UNSERVED] — hard reject with fresh anchors	Undisplayed hunks rejected — same reliance on the model knowing what it saw
Mid-expression / wrong block node	Irrelevant — any verified line range is valid	Grammar rules + PUT N*: node choice; mispointing (anchoring def orphans its decorator) silently lands wrong; no syntax check
Multi-edit batch fails mid-way	edit's edits array — atomic, all-or-nothing; the failing item is echoed as fresh serves	Multi-section patches preflighted up front — also atomic

The 42–53% oh-my-pi payload saving is a lighter wire format; the table above is what that format asks the model to hold in its head instead — renumbering, tag-chasing, node choice — the exact component that fails most (46–51% patch-failure rates on replace-style edits). This plugin's 26% is the price of a contract where a wrong edit cannot land, and any rejection needs no re-read.

Benchmark

Measured on the same 103-line file with the same 12 replacements (8 single-line, 4 multi-line of 3/6/10/15 lines), tokenized with the pinned js-tiktoken cl100k_base. Three arms emit the same replacements: this plugin's edit (two # anchors), a str_replace tool (old text echoed verbatim), and @oh-my-pi/hashline in both of its modes — one [path#tag] section per edit (seq) and one multi-hunk batch document (batch):

Criterion	hashline	str_replace	oh-my-pi seq / batch
Replaced text sent over the wire	✅ never	❌ every edit	✅ never
Output tokens saved (12-edit session)	✅ 26%	❌ 0%	✅ 42% / 53%
Multi-line range savings (3–15 lines)	✅ 29–47%	❌ 0%	✅ 40–53%
Effective cost at 5× output pricing	✅ ~1.4× less	❌ 1×	✅ ~1.7× / ~2.1× less
Ranges veri