edit_file

Replace one or more exact text regions inside an existing file without rewriting it whole. Every edit names an oldText that must match the original file exactly (CRLF and BOM preserved) and a newText to put in its place. Like write_file, edit_file requires an expectedSha256 of the pre-edit content, so concurrent modifications are detected up front.

import { createAgent } from "@comma-agents/core";

const agent = createAgent({
  name: "editor",
  model: "openai/gpt-4o",
  tools: ["read_file", "edit_file"],
});

EditFileToolConfig

Optional configuration for the factory.

AppliedEdit

One entry in data.appliedEdits.

MatchRange

The byte range that was replaced.

EditFileData

The full structured payload.

Edit semantics

Each edit is matched against the original pre-edit snapshot of the file, not against the file as previous edits have left it. This means edits cannot accidentally fix up each other's matches, and overlapping edits are detected before anything is written.

• oldText must be present exactly once in the snapshot unless replaceAll: true is set.
• Multiple matches without replaceAll return multiple_matches.
• An oldText that is not found returns old_text_not_found.
• Two edits whose match ranges intersect return overlapping_edits — the whole call fails atomically.

await tool.edit_file({
  path: "src/server.ts",
  expectedSha256: read.data.sha256,
  edits: [
    { oldText: "const PORT = 3000;", newText: "const PORT = 4000;" },
    { oldText: "console.log(", newText: "logger.info(", replaceAll: true },
  ],
});

Newline and BOM preservation

edit_file operates on the byte content as it is on disk. CRLF line endings inside oldText must be matched verbatim (use the value returned by read_file, which is LF-normalized for content but preserves the underlying style for the write). The BOM is never altered.

Errors

Related

• write_file — when the whole file changes.
• apply_patch — for multi-file diffs and renames.
• Stale file protocol — the full sha256 lifecycle.