Hashline Edit Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Hashline Edit Tool is a specialized file manipulation system within the OhMyOpenCode project that implements hash-anchored editing. It is designed to provide high precision during file modifications by using line-specific content hashes (LINE#ID) to validate line references before applying any changes. This mechanism ensures that edits are only applied if the target file's content matches the state known to the agent at the time of reading, effectively preventing corruption from stale references or concurrent modifications.
The tool operates on a strict Three-Op Model, supporting only replace, append, and prepend operations. It incorporates automated behaviors such as indentation restoration, line-ending preservation (BOM and CRLF), and comprehensive validation pipelines to ensure code quality and structural integrity.
Sources: src/tools/hashline-edit/AGENTS.md:1-12, src/agents/hephaestus/gpt.ts:315-320
Architecture and Execution Pipeline
The Hashline Edit Tool follows a structured execution pipeline to process raw edit requests into a final file state. The process begins with normalization and ends with the generation of a unified diff for verification.
The diagram above illustrates the sequential stages of the hashline edit execution flow, highlighting the central role of hash validation.
Execution Stages
- Normalization: Parses raw input variants into strictly typed
HashlineEditobjects. - Validation: Parses the
LINE#IDformat and verifies that the current file content at the specified line matches the stored hash. - Ordering: Sorts edits in a "bottom-up" fashion (descending by line number) to ensure that earlier edits do not shift the line numbers of subsequent target anchors.
- Deduplication: Removes overlapping or identical operations to prevent redundant processing.
- Application: Performs the actual mutation using low-level line array primitives.
- Autocorrection: Automatically restores indentation and formatting from original lines to maintain code style.
Sources: src/tools/hashline-edit/AGENTS.md:15-30, src/tools/hashline-edit/hashline-edit-executor.ts
Data Models and Formats
LINE#ID Format
The core of the tool's reliability is the LINE#ID format. Every line in a file is treated as an anchored entity.
| Component | Format | Example | Description |
|---|---|---|---|
| Line Number | Integer | 42 | The 1-based index of the line in the file. |
| Separator | # | # | The character separating line number from hash. |
| Hash ID | 2 Characters | VK | A Content ID (CID) derived from the line text. |
Hash Computation: The hash_id is a 2-character CID generated using a specific alphabet set: ZPMQVRWSNKTXJBYH.
Sources: src/tools/hashline-edit/AGENTS.md:52-60
Operations (The Three-Op Model)
The tool restricts all file modifications to three specific primitive operations:
| Operation | Position (pos) | Lines | Description |
|---|---|---|---|
replace | Required | Required/Null | Replaces a line or range. If lines is null/empty, it acts as a deletion. |
append | Optional | Required | Inserts new lines after the specified anchor (defaults to EOF). |
prepend | Optional | Required | Inserts new lines before the specified anchor (defaults to BOF). |
Sources: src/tools/hashline-edit/AGENTS.md:6-12, src/agents/hephaestus/gpt-5-4.ts:160-170
Validation and Error Handling
The validation phase is critical to prevent "hallucinated" edits or applications on stale context.
The sequence above demonstrates how the validation engine protects file integrity by checking provided hashes against real-time content.
Error Scenarios
- Hash Mismatch: If the file was changed since the agent last read it, the hash will not match, and the edit is rejected.
- Overlapping Ranges: Detected if multiple
replaceoperations attempt to modify the same line indices. - Schema Violations: Missing required
posfor a replacement or providingnulllines for insertions.
Sources: src/tools/hashline-edit/validation.ts, src/tools/hashline-edit/AGENTS.md:67-73
Automated Behaviors and Formatting
The tool includes several "quality of life" features to ensure that the resulting code remains clean and matches the project's style:
- Indentation Restoration: Automatically restores the leading whitespace from the original lines to the newly inserted/replaced lines.
- Text Normalization: Preserves Byte Order Marks (BOM) and CRLF line endings found in the original file.
- Line Expansion: If multiple lines are merged during an edit, the tool can auto-expand them back to the original count if necessary.
- Prefix Stripping: Automatically removes diff markers (like
>>>) and pipe separators used in the read output.
Sources: src/tools/hashline-edit/AGENTS.md:61-65, src/agents/hephaestus/gpt-5-4.ts: GPT_APPLY_PATCH_GUIDANCE
Integration in Agent Workflows
In the OhMyOpenCode ecosystem, the hashline_edit tool is the preferred method for surgical code changes by agents like Hephaestus. Agents are instructed to:
- Search the codebase for patterns.
- Read the target file to obtain
LINE#IDtags. - Perform edits using these specific tags to guarantee accuracy.
- Verify changes using
lsp_diagnosticsimmediately after the tool execution.
Sources: src/agents/hephaestus/gpt.ts:315-325, src/agents/hephaestus/gpt-5-4.ts:150-165