hashline-editing

name	hashline-editing
description	Use the Hashline harness to read and edit files with high stability, especially useful for complex refactors or when line numbers are shifting.

Hashline Editing

The Hashline harness provides a stable way to edit files using content hashes as anchors instead of fragile line numbers or full-text replacement.

When to Use

This skill should be used by default for all file editing operations. Prefer Hashline over replace_file_content and multi_replace_file_content tools. It is especially valuable in:

• Complex Edits: When edits span multiple non-contiguous regions or involve whitespace-sensitive code.
• Shifted Code: When file content might have changed (lines inserted/deleted) since your last read.
• High Reliability: When you need to ensure precise targeting of code blocks.

Setup

The scripts live in this skill's scripts/ directory:

skills/hashline_editing/
├── SKILL.md          # This file
└── scripts/
    ├── hashline.py       # Core library
    └── hashline_cli.py   # CLI entry point

Workflow

1. Read with Hashes

Use the CLI to get a "Hashlined" view of any file:

python3 skills/hashline_editing/scripts/hashline_cli.py read <file_path>

Output Format:

12:a3f1| function foo() {
13:b7c2|   return true;
14:9c8a| }

Each line is prefixed with LINE_NUMBER:4_CHAR_HASH|. The hash is derived from the line's content.

2. Apply Edit

Use the edit command with the start and end anchors from the read output:

python3 skills/hashline_editing/scripts/hashline_cli.py edit <file_path> <start_anchor> <end_anchor> <new_content>

Example — replacing a single line:

python3 skills/hashline_editing/scripts/hashline_cli.py edit src/main.py "13:b7c2" "13:b7c2" "  return false;"

Example — replacing a range of lines:

python3 skills/hashline_editing/scripts/hashline_cli.py edit src/main.py "13:b7c2" "14:9c8a" "  return false;\n}"

Using Stdin for Multi-line Content:

cat <<EOF | python3 skills/hashline_editing/scripts/hashline_cli.py edit src/main.py "13:b7c2" "14:9c8a" -
  // New implementation
  return false;
}
EOF

How It Works

• Hashing: Each line's trimmed content is MD5-hashed to a 4-character tag.
• Proximity Search: If the file changes between read and edit (e.g., lines inserted), the harness finds the anchor closest to the expected position rather than failing.
• Empty Lines: Get a reserved hash to avoid ambiguity.

Troubleshooting

• "Error locating start anchor": The file has changed significantly. Re-read with read to get fresh anchors.
• "Resolved end line is before start line": Start and end anchors are swapped.