File Tools: Read, Write, Edit

Claude Code exposes three file-manipulation primitives. They share one invariant: every write operation requires a prior read of the target file. That single rule shapes the entire design.

Pagination: offset + limit

By default Read returns up to 2000 lines starting at line 1. For large files, pass offset (1-based line number) and limit. The default prompt says to read the whole file unless you know the relevant section; the A/B variant (targetedRangeNudge flag) flips that: only read what you need.

// Default call — reads from line 1 up to 2000 lines
Read({ file_path: "/project/src/main.ts" })

// Paginated — start at line 500, read 100 lines
Read({ file_path: "/project/src/main.ts", offset: 500, limit: 100 })

Token limit enforcement

A two-stage gate keeps output bounded. First a fast rough estimate (no API call). If the estimate exceeds ¼ of the cap, an exact token count via API is fetched. If the result exceeds maxTokens (default 25 000), a MaxFileReadTokenExceededError is thrown before the content is ever sent to the model.

Image support

PNG, JPG, JPEG, GIF, and WebP are detected by extension. The file is loaded into memory, optionally resized via sharp (or the native image-processor-napi in bundled builds), and returned as a base64 block for Claude's multimodal input. Dimension metadata travels alongside so coordinates stay correct after resizing.

// Read a screenshot — Claude sees the image visually
Read({ file_path: "~/Documents/screenshots/CleanShot 2026-03-31.png" })

PDF support

When the runtime supports PDFs (isPDFSupported() returns true), the pages parameter accepts ranges like "1-5", "3", or "10-20". A hard cap of 20 pages per call is enforced. Large PDFs that exceed an internal size threshold have their pages extracted as images rather than sent as a single document block.

// Read pages 1 through 5 of a PDF
Read({ file_path: "/docs/spec.pdf", pages: "1-5" })

// Large PDF: exceeds 10 pages requires explicit range
Read({ file_path: "/docs/report.pdf", pages: "6-10" })

Jupyter notebooks

.ipynb files get special handling. Every cell — code, markdown, outputs, visualizations — is passed through mapNotebookCellsToToolResult() which stitches them into a coherent tool result. The model sees a unified view of the notebook rather than raw JSON.

readFileState.set(fullFilePath, {
  content,
  timestamp: getFileModificationTime(fullFilePath),
  offset, // undefined means "full read"
  limit,
})

"File unchanged since last read. The content from the earlier
Read tool_result in this conversation is still current —
refer to that instead of re-reading."

// Infinite output — never reach EOF
'/dev/zero', '/dev/random', '/dev/urandom', '/dev/full'

// Blocks waiting for input
'/dev/stdin', '/dev/tty', '/dev/console'

// fd aliases for stdio (also Linux /proc/self/fd/0-2)
'/dev/fd/0', '/dev/fd/1', '/dev/fd/2'

Write is a full-content replacement. It either creates a new file or overwrites an existing one entirely. For surgical changes to existing files, the prompt explicitly says to prefer Edit — it only sends the diff.

The read-before-write gate

If a file already exists on disk, Write requires a prior Read of that file. The tool checks readFileState for the file path. Three failure modes are distinct error codes:

Line-ending policy

Write always persists content with LF line endings, regardless of the old file's endings or the repo's conventions. This is intentional. A previous approach that preserved or inferred line endings silently corrupted bash scripts when overwriting a CRLF file on Linux, or when binaries in the cwd poisoned a repo-wide ripgrep sample.

Atomic write sequence

The critical section between reading current content and writing to disk is kept as synchronous as possible to prevent concurrent edits from interleaving:

// 1. mkdir (async, before critical section — safe)
await fs.mkdir(dir)

// 2. Backup for file history (async, keyed on content hash — idempotent)
await fileHistoryTrackEdit(...)

// 3. Sync read + staleness check (critical section starts)
meta = readFileSyncWithMetadata(fullFilePath)
if (lastWriteTime > lastRead.timestamp) throw FILE_UNEXPECTEDLY_MODIFIED_ERROR

// 4. Write to disk (critical section ends)
writeTextContent(fullFilePath, content, enc, 'LF')

Edit performs an exact string replacement: find old_string in the file and replace it with new_string. Only the diff is transmitted — far cheaper than Write for small changes.

String replacement mechanics

The search is a direct substring match. If the string appears more than once, Edit refuses with error 9 unless replace_all: true is passed. This forces Claude to provide enough surrounding context to be unambiguous.

// Unambiguous — narrow match
Edit({
  file_path: "/src/config.ts",
  old_string: "const MAX_RETRIES = 3",
  new_string: "const MAX_RETRIES = 5",
})

// Replace all occurrences of a variable name
Edit({
  file_path: "/src/utils.ts",
  old_string: "oldFunctionName",
  new_string: "newFunctionName",
  replace_all: true,
})

Quote normalization

Claude cannot output curly (typographic) quotes — the API sanitizes them. The Edit tool solves this with a two-step process:

const msg = "Hello, world"
// "Hello" uses U+201C/U+201D

const msg = "Hello, world"
// Claude can only type ASCII "

findActualString() normalizes both the file and the search string to straight quotes, locates the match, and returns the original curly-quote version from the file. Then preserveQuoteStyle() applies the same curly-quote style to new_string, so the file's typography is preserved after the edit.

// normalizeQuotes() under the hood:
str
  .replaceAll('\u2018', "'")  // left single curly
  .replaceAll('\u2019', "'")  // right single curly
  .replaceAll('\u201C', '"')  // left double curly
  .replaceAll('\u201D', '"')  // right double curly

New file creation via Edit

Setting old_string: "" on a non-existent file creates it. Setting it on an existing empty file replaces it. Setting it on a non-empty file fails with "Cannot create new file — file already exists." This makes the intent explicit.

Staleness check (same as Write)

Edit shares Write's staleness logic. The critical section reads the file synchronously, checks mtime against readFileState, and throws FILE_UNEXPECTEDLY_MODIFIED_ERROR if the file changed after the last read. The content-comparison fallback for full reads on Windows applies here too.

'<fnr>'           → '<function_results>'
'<n>'             → '<name>'
'<o>'             → '<output>'
'<e>'             → '<error>'
'\n\nH:'          → '\n\nHuman:'
'\n\nA:'          → '\n\nAssistant:'
// ...and several more special tokens

The same change — updating a constant from 3 to 5 — done both ways. Edit is almost always the right choice for existing files.

// Must include the ENTIRE file content
Write({
  file_path: "/src/config.ts",
  content: `import { z } from 'zod'

export const config = {
  maxRetries: 5,   // changed
  timeout: 3000,
  endpoint: "https://api.example.com",
}
`
})

// Sends the whole file every time.
// 150+ lines → 150+ lines of tokens.

// Only the changed fragment needed
Edit({
  file_path: "/src/config.ts",
  old_string: "maxRetries: 3,",
  new_string: "maxRetries: 5,",
})

// Sends ~20 characters.
// Costs a fraction of Write.

//
//

Both Write and Edit enforce the same three-phase contract. Understanding it prevents the most common tool errors.