AX-Copilot/docs/claude-code-docs-main/en/reference/tools/file-operations.md

Documentation Index

Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.

File Operations

Read, edit, and write files on the local filesystem.

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

Absolute path to the file. Relative paths are not accepted. Line number to start reading from (1-indexed). Use this with `limit` to read a specific section of a large file. 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

Type	Behavior
Text files	Returns raw text with line numbers
Images (PNG, JPG, etc.)	Displayed visually — Claude is multimodal
PDF files	Returned 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

Absolute path to the file to modify. The exact string to find and replace. Must match the file content character-for-character, including whitespace and indentation. The replacement string. Use an empty string to delete `old_string`. 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

Absolute path to the file to create or overwrite. 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.

* 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.

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

Built with Mintlify.