Skip to main content
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.
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
required
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

TypeBehavior
Text filesReturns raw text with line numbers
Images (PNG, JPG, etc.)Displayed visually — Claude is multimodal
PDF filesReturned as document content. For PDFs over 10 pages, use the pages parameter (e.g., "1-5"). Maximum 20 pages per request.
Jupyter notebooks (.ipynb)All cells and outputs are returned, combining code, text, and visualizations
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
required
Absolute path to the file to modify.
​
old_string
string
required
The exact string to find and replace. Must match the file content character-for-character, including whitespace and indentation.
​
new_string
string
required
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.
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
required
Absolute path to the file to create or overwrite.
​
content
string
required
The complete content to write to the file. If the file already exists, it is replaced entirely.

​
When to use Write vs 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.

​
Pre-read requirement

When overwriting an existing file, Claude must call Read first. Write enforces this to prevent unintentional data loss.
Claude does not proactively create documentation files (*.md, README.*) unless explicitly instructed. Write follows the same principle.