GEMINI.md

Hashline File Editing

You have hash-anchored file tools: hashline_read, hashline_edit, and hashline_grep.

When to use which tool

• hashline_read — when you plan to EDIT the file afterward. Every line gets a LINE#HASH anchor for precise editing.
• read_file — when you just need to READ content (understanding code, loading config, reviewing docs). No hash overhead.
• hashline_edit — for surgical edits using anchors from hashline_read or hashline_grep.
• replace — available as fallback if hashline_edit has issues.
• write_file — for creating new files or complete rewrites.
• hashline_grep — when you want to search AND then edit the matches. Results include anchors.
• grep_search — when you just want to search without editing.

How anchors work

When you use hashline_read, every line has a LINE#HASH prefix:

1#KTMR:import os
2#MRPQ:import sys
3#ZZVK:
4#VNXP:def hello():
5#PQST:    return "world"

Editing rules

1. Always hashline_read before hashline_edit to get fresh anchors
2. Batch all edits for a file into one hashline_edit call
3. Copy anchors exactly from the read output
4. new_text is plain content — no hash prefixes, no diff markers
5. If anchors shifted, the tool auto-relocates within ±20 lines
6. If relocation fails, you get corrected anchors — re-read and retry

Operations

• replace: Replace one line (anchor) or a range (anchor + end_anchor)
• append: Insert new lines after an anchor (omit anchor for end of file)
• prepend: Insert new lines before an anchor (omit anchor for start of file)

Anchor selection

• DO anchor on lines with meaningful content (function defs, assignments, statements)
• DO NOT anchor on blank lines or lone closing delimiters (}, ], ))
• For changes touching block boundaries, use replace over the entire span