File Operations

Claude Code has three dedicated tools for working with files: Read for reading content, Edit for precise in-place edits, and Write for creating or fully rewriting files.

Tip: Prefer Edit over Write when modifying existing files — Edit sends only the changed fragment, saving context and reducing the chance of unintended overwrites.

---

Read

Reads a file from the local filesystem and returns its contents with line numbers.

Parameters

• file_path (string) — Absolute path to the file. Relative paths are not accepted.

• offset (number) — Line number to start reading from (1-indexed). Use this with limit to read a specific section of a large file.

• limit (number) — Maximum number of lines to return. Defaults to 2,000 lines. For files longer than this, call Read again with a higher offset to page through the content.

Output format

Results use cat -n style formatting: each line is prefixed with its 1-indexed line number.

   1  import { z } from 'zod'
   2
   3  export const schema = z.object({
   4    name: z.string(),
   5  })

Claude preserves exact indentation from this output when constructing Edit calls.

Supported file types

Note: Read cannot list directories. To inspect a directory's contents, use ls via the Bash tool.

Caching

If a file has not changed since the last Read call in the same conversation, Claude receives a cached stub instead of re-reading the file. This avoids redundant reads on unchanged files.

---

Edit

Performs exact string replacement within a file.

Parameters

• file_path (string) — Absolute path to the file to modify.

• old_string (string) — The exact string to find and replace. Must match the file content character-for-character, including whitespace and indentation.

• new_string (string) — The replacement string. Use an empty string to delete old_string.

• replace_all (boolean) — When true, replaces every occurrence of old_string in the file instead of only the first. Useful for renaming variables or symbols that appear multiple times.

How Edit works

Edit finds the literal text in old_string inside the file and substitutes it with new_string. No regex interpretation occurs — the match is a plain string comparison.

Warning: The tool fails if old_string appears more than once in the file and replace_all is not set. Provide enough surrounding context in old_string to make it unique, or set replace_all: true to update all occurrences.

Pre-read requirement

Claude must call Read on a file at least once in the conversation before calling Edit on it. The tool enforces this to prevent edits based on stale or assumed content.

Indentation matching

When Claude derives old_string from Read output, it uses the content that appears after the line-number prefix. For example, given:

  12      const x = 1

The old_string is const x = 1 (six leading spaces), not 12 const x = 1.

---

Write

Creates a new file or fully overwrites an existing one.

Parameters

• file_path (string) — Absolute path to the file to create or overwrite.

• content (string) — The complete content to write to the file. If the file already exists, it is replaced entirely.

When to use Write vs Edit

Use Edit

• Modifying one or more sections of an existing file

  • Renaming a variable or symbol across the file
  • Adding or removing a block of code

  Edit is preferred because it transmits only the changed fragment.

  Use Write

• Creating a new file from scratch

  • Completely rewriting a file (e.g., regenerating a config from new requirements)
  • When the new content is entirely different from the original

  Write replaces the entire file in one call.

Pre-read requirement

When overwriting an existing file, Claude must call Read first. Write enforces this to prevent unintentional data loss.

Warning: Claude does not proactively create documentation files (*.md, README.*) unless explicitly instructed. Write follows the same principle.