> ## Content Index > Fetch the complete content index at: https://wuu73.org/aiguide-ghost/llms.txt > Use this file to discover other available public pages before exploring further. # Agent Deep Dives - URL: https://wuu73.org/aiguide-ghost/coding-file-edits-agents/ - Published: 2026-05-29T00:02:00.000Z - Updated: 2026-05-29T00:02:00.000Z - Description: Part of How Agent Harnesses Edit Files. - Author: WUU73 - Tags: Deep Dives, Coding File Edits, #Deep Dive Child, #Import 2026-09-12 06:38 Each AI coding agent has a distinct philosophy for file editing. Here's what makes each one uniqueβ€”and what you can learn from them. #### Jump to Agent [Cline](#cline) [Codex / Claude Code](#codex) [OpenCode](#opencode) [ADK-Rust](#adk-rust) [Aider](#aider) [Grok CLI](#grok) [Crush](#crush) [DeerFlow](#deerflow) [Dirac](#dirac) [Oh My Pi](#oh-my-pi) [Goose](#goose) [OpenHands](#openhands) [Pi / Pochi / Qwen](#pi-pochi-qwen) [Wintermolt / Zaica](#zig-agents) ## 🎯 Cline β€” The Precision Specialist Cline is a VS Code extension that takes a **"trust but verify"** approach. It doesn't trust the AI to get whitespace perfect, so it implements heavy fallback logic to handle the inevitable mismatches. ### Philosophy > "Default to `replace_in_file` for safety and precision. Only use `write_to_file` for new files or when edits fail repeatedly." β€” Cline's system prompt instructions ### Primary Tools | Tool | Purpose | Format | | ----------------- | ---------------------------------- | ------------------------------ | | replace\_in\_file | Surgical search/replace edits | XML with SEARCH/REPLACE blocks | | write\_to\_file | Create new files, fallback rewrite | XML with full content | | apply\_patch | V4A diff format (GPT-5 only) | Custom patch syntax | ### The 4-Tier Matching Strategy Cline's `constructNewFileContent` function in `src/core/assistant-message/diff.ts` implements this cascade: 1**Exact Match** Direct `indexOf()` β€” byte-for-byte string comparison ↓ if fails2**Line-Trimmed Fallback** Compare lines after `.trim()` β€” handles indentation differences ↓ if fails3**Block Anchor Fallback** Match first/last lines as anchors (for blocks β‰₯3 lines) ↓ if fails4**Full-File Search** Search entire file from start β€” supports out-of-order replacements ### Special Features - **Streaming UI updates:** Real-time diff preview as AI generates content - **Model content fixes:** Strips markdown code blocks, fixes HTML entities (`&` β†’ `&`) - **Approval flow:** Configurable auto-approval or manual confirmation - **After 3 failures:** Suggests fallback to `write_to_file` πŸ’‘ #### What to Borrow Cline's tiered fallback approach and model content fixes are battle-tested. If you're building a VS Code extension, study their streaming diff UI implementation. ## πŸ”§ Codex / Claude Code β€” The Patch Master Codex (the CLI behind Claude Code) treats file editing like **version control**. It uses a custom patch format that feels like `git diff` with enhanced semantics for add/update/delete operations. ### Philosophy > "Patches are the native language of code changes. Make the AI speak in patches, and you get efficient, reviewable, multi-file edits." ### The Patch Format Codex Patch Syntax ``` *** Begin Patch *** Add File: src/new_module.py +"""Module docstring""" + +def new_function(): + return True *** Update File: src/existing.py @@ def greet(): @@ """Say hello""" - print("Hi") + print("Hello, world!") *** Delete File: src/deprecated.py *** Move to: src/renamed.py *** End Patch ``` ### Key Markers | Marker | Purpose | | -------------------------- | ------------------------- | | \*\*\* Begin Patch | Start of patch block | | \*\*\* Add File: | Create a new file | | \*\*\* Update File: | Modify existing file | | \*\*\* Delete File: | Remove a file | | \*\*\* Move to: | Rename file (with Update) | | @@ | Context for locating edit | | + / \- | Add / remove lines | | \*\*\* End Patch | End of patch block | ### Fuzzy Matching: `seek_sequence` Codex's Rust implementation uses a `seek_sequence` function with 4 levels of tolerance: 1. **Exact match:** Byte-for-byte equality 2. **Trailing whitespace tolerant:** Ignore trailing spaces 3. **Leading/trailing tolerant:** Ignore surrounding whitespace 4. **Unicode normalization:** Handle different dashes (β€”, –, -), quotes (" vs "), etc. ### Why Custom Format? The custom patch format has several advantages over standard unified diff: - **No line numbers:** Uses context lines (`@@`) instead of fragile line counts - **Multi-level context:** Can stack `@@` markers for unique identification - **Semantic operations:** Clear add/update/delete/move semantics - **Heredoc support:** Can be embedded in shell scripts πŸ’‘ #### What to Borrow Unicode normalization is underrated. AI models often use "smart quotes" or em-dashes when matching code that uses ASCII equivalents. Codex handles this gracefully. ## πŸ› οΈ OpenCode β€” The Fallback King OpenCode takes the philosophy of **"maximize success probability through redundancy"** to its extreme. It implements **9 different matching algorithms** that are tried sequentially. ### Philosophy > "If we have enough fallbacks, eventually something will match. And if it doesn't, we tell the AI exactly what went wrong so it can self-correct." ### Core Tools | Tool | File | Purpose | | ------------- | ----------------- | --------------------------------------- | | EditTool | tool/edit.ts | Primary search/replace with 9 fallbacks | | WriteTool | tool/write.ts | Full file creation/overwrite | | MultiEditTool | tool/multiedit.ts | Atomic multi-edit in one file | | PatchTool | tool/patch.ts | Unified diff-style patches | | ReadTool | tool/read.ts | Read with offset/limit (2000 lines) | ### The 9 Fallback Replacers When `EditTool` tries to apply an edit, it cascades through: | # | Replacer | What It Does | | - | ---------------------------- | -------------------------------------------- | | 1 | SimpleReplacer | Exact match, then escaped version | | 2 | LineTrimmedReplacer | Trim each line before comparing | | 3 | BlockAnchorReplacer | Match first/last lines + similarity check | | 4 | WhitespaceNormalizedReplacer | Convert multiple spaces/tabs to single space | | 5 | IndentationFlexibleReplacer | Remove common indentation prefix | | 6 | EscapeNormalizedReplacer | Unescape \\n, \\t, \\", etc. | | 7 | TrimmedBoundaryReplacer | Trim entire block boundaries | | 8 | ContextAwareReplacer | 50% similarity threshold with context | | 9 | MultiOccurrenceReplacer | Find all matches (for replaceAll) | ### LSP Integration OpenCode is unique in its deep Language Server Protocol integration. After every edit: 1. Refresh the LSP file watcher 2. Check for diagnostics (syntax errors, type errors) 3. Append errors to the tool response in XML format LSP Error Response ``` Line 14: 'subtotal' is not defined. Line 22: Expected ';' but found '}'. ``` This immediate feedback loop helps the AI self-correct without human intervention. πŸ’‘ #### What to Borrow The 9-layer fallback system is overkill for most cases, but the `EscapeNormalizedReplacer` is brilliant. AI models often output `\n` as the literal string instead of a newlineβ€”this handles that case. ## πŸ—οΈ ADK-Rust β€” The Provider Delegate ADK-Rust is the cleanest counterexample in this set to the fallback-heavy editing philosophy. Instead of building a giant local matcher, it wraps provider-native editing contracts and keeps the local execution layer thin. ### Philosophy > "Expose the provider's own editing contract cleanly, fail sharply, and let the caller retry with better context instead of guessing." ### Core Tools | Tool | Where it lives | Purpose | | ------------------------- | --------------------------------- | ----------------------------------------- | | AnthropicTextEditorTool\* | adk-tool/src/builtin/anthropic.rs | Native view, str\_replace, insert, create | | OpenAIApplyPatchTool | adk-tool/src/builtin/openai.rs | Declares provider-native apply\_patch | | AnthropicBashTool\* | adk-tool/src/builtin/anthropic.rs | Shell escape hatch via sh -lc | ### What Makes It Different - **Exact means exact:** `str_replace` fails if the old string appears zero times or more than once. - **1-based lines:** Insert and view operations use human-style line numbering. - **No giant rescue stack:** No whitespace normalizer, no anchor fallback, no diff-match-patch retry loop. - **Provider-native patching:** OpenAI patch semantics are delegated to the Responses API protocol layer. πŸ’‘ #### What to borrow If you are building a framework instead of a product, this is a strong pattern. Keep the editor primitive strict, typed, and honest. Let models recover from sharp errors instead of letting your framework guess. ## ⚑ Aider β€” The Format Flexible Aider stands out by supporting **three different edit formats** and choosing the right one based on the model's strengths. It's the most research-driven approach to format selection. ### Philosophy > "Different models have different strengths. GPT-4 does better with whole files. Claude does better with search/replace. Match the format to the model." ### The Three Formats SEARCH/REPLACE (diff)WHOLE FILEUNIFIED DIFF #### Format 1: SEARCH/REPLACE ``` filename.py ```python <<<<<<< SEARCH def old_function(): return False ======= def old_function(): return True >>>>>>> REPLACE ``` ``` **Best for:** Targeted edits, most models **Model defaults:** Claude 3.5, o3-mini #### Format 2: WHOLE FILE ``` filename.py ```python # Entire file content import sys def main(): print("Hello!") if __name__ == '__main__': main() ``` ``` **Best for:** New files, small files, massive refactors **Model defaults:** GPT-4o, Claude 3.5 Sonnet **Critical rule:** No elision with `...` β€” must include everything! #### Format 3: UNIFIED DIFF ``` --- filename.py +++ filename.py @@ ... @@ -def old(): - return False +def old(): + return True ``` **Best for:** Models trained on diffs, token efficiency **Challenge:** High cognitive load, easy to hallucinate context ### Fuzzy Matching Cascade Aider's `search_replace.py` implements 5 fallback strategies: 1. **Exact match:** Direct string find 2. **Flexible whitespace:** Normalize spaces/tabs 3. **Relative indentation:** Transform to relative indents 4. **Git cherry-pick:** Use git to apply patch 5. **Diff-match-patch:** Google's fuzzy matching library ### Model Configuration Aider maintains a `model-settings.yml` with format defaults: YAML ``` gpt-4o: edit_format: "whole" o3-mini: edit_format: "diff" claude-3.5-sonnet: edit_format: "whole" ``` πŸ’‘ #### What to Borrow The model-specific format defaults are based on empirical testing. If you support multiple models, consider profiling which format works best for each and making it configurable. ## πŸš€ Grok CLI β€” The Dual-Mode Agent Grok CLI combines a traditional text editor tool with an optional **Morph AI-powered fast editing** mode. It's unique in offering both procedural and AI-assisted editing paths. ### Philosophy > "Give the AI multiple tools for different situations. Use str\_replace for precision, Morph for speed (4,500+ tokens/sec), and always show diffs before writing." ### Core Tools | Tool | Method | Purpose | | --------------- | -------------- | --------------------------------------- | | TextEditorTool | view() | Read file with line numbers | | TextEditorTool | create() | Create new file (confirmation required) | | TextEditorTool | strReplace() | Search/replace with fuzzy matching | | TextEditorTool | replaceLines() | Line-range replacement | | TextEditorTool | insert() | Insert at line number | | TextEditorTool | undoEdit() | Revert last edit | | MorphEditorTool | editFile() | AI-powered fast apply (4,500+ tok/sec) | ### Morph Editor Syntax The Morph editor uses a special `// ... existing code ...` syntax to represent unchanged sections: Morph Edit Syntax ``` // ... existing code ... import { newDependency } from 'new-package'; // ... existing code ... function updatedFunction() { return newImplementation(); } // ... existing code ... ``` The AI model writes what it wants to change, and the Morph Fast Apply API merges it with the existing file at high speed. ### User Confirmation System Grok CLI's `ConfirmationService` provides robust safety: - **Session flags:** Users can skip confirmations for file ops, bash commands, or all - **Diff-style preview:** Every change shows before/after with `+/-` markers - **Granular approval:** Approve single operation or "don't ask again" per type Confirmation Preview ``` Updated example.js with 2 additions and 1 removal --- a/example.js +++ b/example.js @@ -1,3 +1,4 @@ function test() { + console.log("added"); return "value"; - oldLine(); } ``` ### Fuzzy Function Matching Grok CLI's `strReplace` includes intelligent function signature matching using token analysis and brace counting. It can find the right function even if the AI slightly misquotes the body. πŸ’‘ #### What to Borrow The confirmation service with session flags is excellent UX. Users can start cautious and "unlock" auto-approval as they build trust. The undo capability is also underused in other agents. ## πŸ’Ž Crush & Neovate Code β€” The JSON String-Replacers Crush and Neovate Code represent the pragmatic TypeScript/Go CLI style: expose small JSON-schema tools, make the model provide literal old/new strings, then compensate for inevitable whitespace drift with layered matching. ### Crush: explicit edit/write/multiedit tools Crush defines file mutation tools in `internal/proto/tools.go` and implements them under `internal/agent/tools/`: | Tool | Parameters | Role | | --------- | -------------------------------------------------- | ------------------------------- | | edit | file\_path, old\_string, new\_string, replace\_all | Targeted replacement | | multiedit | file\_path, array of old/new operations | Several edits in one file | | write | file\_path, content | Create or overwrite entire file | | view | file\_path, offset, limit | Read context before editing | The interesting guardrail is freshness: `write.go` checks the file's modification time against the session's last-read timestamp and refuses to overwrite a file that changed since the model last viewed it. It also emits diff metadata (`additions`, `removals`) for permission dialogs and review. ### Neovate Code: OpenCode-style fallback cascade Neovate's `src/utils/applyEdit.ts` applies old/new string edits through a six-step cascade: 1. Exact match 2. Line-trimmed match 3. Block-anchor match using first/last lines plus similarity 4. Whitespace-normalized match 5. Escape-normalized match for over-escaped model output 6. Indentation-flexible match πŸ’‘ #### What to Borrow Crush's last-read guard prevents stale overwrites; Neovate's fallback chain is a compact version of OpenCode's redundancy without requiring a full diff parser. ## 🦌 DeerFlow & Hermes β€” Sandbox Tools over Editor Primitives DeerFlow and Hermes are less about a bespoke patch algorithm and more about **tool hosting**. File operations are registered tools that can be enabled, disabled, sandboxed, and composed with bash or MCP-like extensions. DeerFlow's setup wizard registers `write_file` and `str_replace` as `file:write` tools in `scripts/wizard/writer.py`, pointing at `deerflow.sandbox.tools:write_file_tool` and `deerflow.sandbox.tools:str_replace_tool`. That makes editing a capability of the sandbox configuration rather than a hard-coded agent behavior. Hermes follows the same tool-registry philosophy. Its tool catalogs group file capabilities such as `read_file`, `write_file`, `patch`, and `search_files`, while hooks can observe or gate tool use before and after execution. ## πŸͺΏ Goose β€” Extension-First File Editing Goose deliberately keeps the core agent lean. In the main field guide, the key phrase is "extension-first": file editing, web search, databases, and specialized workflows come through extensions rather than a giant built-in tool list. This changes the file-editing story: the agent's reliability depends on which extension/tool server provides editing. Goose's core contribution is the inspection pipeline around tool calls β€” security, egress, adversary, permission, and repetition inspectors β€” not a single canonical text matcher. πŸ”Œ #### Design lesson If your agent is extension-first, define capability contracts and review boundaries as carefully as other agents define SEARCH/REPLACE syntax. ## πŸ“Œ Dirac β€” Hash-Anchored, AST-Aware Editing Dirac is the outlier: it attacks coordinate drift directly. Instead of trusting line numbers or brittle search snippets, Dirac reads files with stable line hashes and asks edits to target `anchor` and `end_anchor` values. The important implementation pieces are documented in the main guide: `src/core/task/tools/handlers/edit-file/EditExecutor.ts` resolves anchors and validates that the content at the anchor still matches, while `BatchProcessor.ts` applies resolved edits in reverse line order. - **Line-shift resistant:** edits survive unrelated insertions above the target. - **Batch-friendly:** multiple disjoint changes can be applied in one roundtrip. - **Fail-fast validation:** stale anchors produce explicit diagnostics. - **Structural layer:** AST-aware symbol tools handle functions/classes without raw text matching. πŸ“Œ #### What to Borrow Hash anchors are a strong alternative when you want multi-edit batching without relying on huge old\_string contexts or fragile line numbers. ## πŸ§ͺ Oh My Pi β€” Hashline Editing as a Whole-System Design Oh My Pi is interesting because it does not treat its anchor format as a one-off trick. In the current repo, `hashline` is the **default edit mode**, `readHashLines` is on by default, prompt helpers can render real anchors, and the executor itself handles multi-section validation, same-path merge logic, nearby rebasing, and BOM/line-ending preservation. That makes it a useful contrast to both neighbors. Compared with **Dirac**, OMP uses lighter inline line-plus-hash markers rather than persistent word anchors. Compared with **Pi Mono**, it no longer bets on exact old/new text alone; it moves editing toward an anchor-aware protocol and builds benchmarks around that choice. - **Default, not optional:** hashline is the normal path, not a niche mode buried behind flags. - **Batch-aware:** multi-section edits are preflighted and same-file sections are merged before writeback. - **Drift-tolerant:** nearby anchor rebasing gives small line shifts a chance to succeed without reopening fuzzy matching. - **Measured:** the dedicated edit benchmark package shows the team is testing edit protocols, not just asserting they work. 🧭 #### What to borrow If you like the idea of anchors, copy the whole loop: anchored reads, prompt helpers, executor validation, and a benchmark suite. Copying only the syntax is the least important part. ## 🧩 OpenHands & OpenClaudeCode β€” Standard Editor Command APIs OpenHands exposes editor behavior through the familiar `str_replace_editor` family when the standard editor is enabled (`openhands/core/config/agent_config.py`). OpenClaudeCode's snapshot includes Anthropic-style `str_replace_editor` schemas in its vendored SDK. **Important note:** The local OpenHands snapshot is **legacy V0 code**, deprecated since v1.0.0 and scheduled for removal April 1, 2026\. The modern V1 agent core lives in a separate Software Agent SDK repository. What's here is still architecturally interesting, but the current editor config is frozen legacy. This interface is intentionally small: view a file, create a file, replace a unique string, insert after a line, and sometimes undo. It is easier for models to learn than unified diff, but less expressive for multi-file refactors. | Command | Typical use | | ------------ | --------------------------------------------------- | | view | Read current contents with line context | | create | Create a new file from full content | | str\_replace | Replace one exact old string with a new string | | insert | Add content at a line boundary | | undo\_edit | Revert the previous editor operation when supported | ## βš™οΈ Pi, Pochi & Qwen Code β€” Exact Replacement with Guardrails These agents share a conservative pattern: make the model supply literal old and new text, require enough context to identify a unique match, then show a diff or reject the edit with a precise error. ### Pi Mono Pi's default tool set is `read`, `bash`, `edit`, and `write`. Its edit logic supports multiple disjoint old/new replacements per call, validates all matches against the original file, applies replacements in reverse order, preserves CRLF/BOM, and serializes same-file mutations through a per-file queue. ### Pochi Pochi's `packages/tools/src/apply-diff.ts` defines a client-side edit tool with `path`, `searchContent`, `replaceContent`, and optional `expectedReplacements`. It explicitly tells the model to include 3–5 lines of context and rejects ambiguous edits unless the expected replacement count is supplied. ### Qwen Code Qwen Code registers `EditTool` and `WriteFileTool` in `packages/core/src/tools/`. `edit.ts` requires absolute paths, exact literal `old_string`/`new_string`, unique matches by default, and `replace_all` for global edits. It also normalizes line endings for processing while preserving the original line ending, BOM, and detected encoding on write. ## 🧊 Kimi CLI, Wintermolt & Zaica β€” Shell, Patch, and Minimal Tool Cores Some repos in this workspace are less focused on a custom editor algorithm and more focused on being small, native, or provider-flexible. Their editing story tends to be a combination of direct file-write tools, shell commands, and patch utilities. - **Kimi CLI / Zaica's embedded Kimi CLI:** exposes file edit events and `WriteFile`\-style tool calls, with approval and diff display tests around file writes. - **Wintermolt:** a compact Zig-native agent where file mutation is part of a small built-in tool surface rather than a large patch engine. - **Zaica:** a focused Zig agent emphasizing chain-mode and sub-agent workflow; edits are typically simple write/patch/shell actions guarded by the broader workflow state rather than fuzzy text matching. ## Side-by-Side Comparison | Feature | Cline | Codex | OpenCode | Aider | Grok | | -------------------- | -------------- | ------------ | -------------- | --------------- | ---------- | | **Primary Method** | Search/Replace | Custom Patch | Search/Replace | Format-flexible | Dual mode | | **Fallback Layers** | 4 | 3-4 | 9 | 5 | 2+ | | **LSP Integration** | Partial | Minimal | Full | Minimal | No | | **Multi-File Edits** | Sequential | One Patch | Sequential | Sequential | Sequential | | **User Approval** | Configurable | Required | Configurable | Auto | Full diff | | **Undo Support** | Via git | Via git | Via git | Via git | Built-in | | **Token Format** | XML | Custom | JSON-ish | Markdown | Mixed | ### Additional repos in this workspace | Agent / Repo | Primary Method | Notable Guardrail | Key Files / Clues | | ----------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------ | | **Crush** | JSON edit, multiedit, write | Last-read freshness check before overwrite | internal/proto/tools.go, internal/agent/tools/write.go | | **Neovate Code** | Search/replace with 6 fallback strategies | Whitespace, escape, block-anchor, and indentation fallbacks | src/utils/applyEdit.ts | | **DeerFlow** | Sandbox write\_file and str\_replace | Tool groups can enable/disable file writes | scripts/wizard/writer.py | | **Dirac** | Hash-anchored edits plus AST-aware tools | Anchor validation catches drift before writing | EditExecutor.ts, BatchProcessor.ts | | **Goose** | Extension-provided file editing | Inspection pipeline gates tool calls | crates/goose/src/agents/, extension system | | **OpenHands** | str\_replace\_editor standard editor | Sandboxed runtime, configurable editor enablement | openhands/core/config/agent\_config.py | | **Pi Mono** | Multi-edit old/new replacement | Same-file mutation queue, BOM/CRLF preservation | edit-diff.ts, file-mutation-queue.ts | | **Oh My Pi** | Default hashline with fallback edit modes | Hashline preflight, nearby rebase, BOM/CRLF preservation | hashline.ts, line-hash.ts, edit-mode.ts | | **Pochi** | searchContent β†’ replaceContent | expectedReplacements prevents accidental global edits | packages/tools/src/apply-diff.ts | | **Qwen Code** | EditTool and WriteFileTool | Absolute paths, uniqueness checks, encoding preservation | packages/core/src/tools/edit.ts, write-file.ts | | **Kimi / Wintermolt / Zaica** | Write/patch/shell-oriented minimal tools | Approval/diff display or workflow-level control | Tool tests and compact native tool cores | ## Design Philosophy Summary #### Cline "Don't trust AI whitespace. Build fallbacks that handle the inevitable mismatches." #### Codex "Make file editing feel like version control. Patches are the right abstraction." #### OpenCode "If we throw enough algorithms at the problem, something will stick. And validate with LSP." #### Aider "Different models need different formats. Test empirically and configure appropriately." #### Grok CLI "Give users control. Show diffs, ask for approval, and make everything reversible." #### Dirac "Don't search for code. Hash every line with FNV-1a, map to unique word anchors, and let the LLM reference anchors directly. No fuzzy matching, no whitespace sensitivity, no retry loops." #### Oh My Pi "If anchors matter, make them the default language of the system: anchored reads, prompt helpers, edit-mode routing, and benchmarks should all agree on the same contract." #### Crush / Neovate "Keep the tool API simple, but make the matcher forgiving enough for real model output." #### Pochi / Qwen / Pi "Exact old/new text is safe when you require context, uniqueness, preview diffs, and encoding preservation." #### Goose / DeerFlow / Hermes "Make file editing a governed capability in the tool host, not a monolithic hard-coded primitive." [← Editing MethodsThe five fundamental approaches](https://wuu73.org/aiguide-ghost/coding-file-edits-methods/)[Prompts & Instructions β†’How agents tell AI models to use tools](https://wuu73.org/aiguide-ghost/coding-file-edits-prompts/)