File operation tools

Claude uses five dedicated tools for working with files. These tools are preferred over shell commands because they provide clearer permission boundaries and more informative output in the UI.

Read

Reads a file from the local filesystem. The file path must be an absolute path. Read supports text files, images (PNG, JPG, and other common formats), PDFs, and Jupyter notebooks (.ipynb). Images are returned visually. Notebooks return all cells with their outputs.

Inputs

file_path

string

required

Absolute path to the file to read.

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 read. Defaults to 2,000. Combine with offset to page through large files.

pages

string

For PDF files only. Specifies which pages to read (for example, "1-5" or "3"). Required for PDFs longer than 10 pages. Maximum 20 pages per request.

Output

Returns file contents with line numbers in cat -n format (lines prefixed with their line numbers). If the file has not changed since the last Read call in the conversation, Claude receives a stub indicating the content is unchanged rather than re-reading the full file.

Notes

The tool reads files only — it cannot list directory contents. Use Bash with ls to list directories.
If the file does not exist, an error is returned (this is expected behavior).
If the file is empty, a system reminder note is returned in place of content.

Example

Read:
  file_path: /home/user/project/src/index.ts
  offset: 100
  limit: 50

Write

Creates or overwrites a file on the local filesystem.

Write overwrites the entire file. For targeted changes to existing files, use Edit instead — it sends only the diff, which makes it easier to review.

Inputs

file_path

string

required

Absolute path to the file to write. Intermediate directories are not created automatically — use Bash with mkdir -p first if needed.

content

string

required

The full content to write to the file.

Output

Returns a confirmation that the file was written, along with a diff showing what changed from the previous contents (if the file already existed).

Notes

If the file already exists, Claude must read it with Read before calling Write. The tool will fail if the file was not previously read in the conversation.
Use Write when creating new files or performing a complete rewrite. For incremental changes, prefer Edit.

Example

Write:
  file_path: /home/user/project/src/utils/format.ts
  content: |
    export function formatDate(date: Date): string {
      return date.toISOString().split('T')[0]
    }

Edit

Performs an exact string replacement in an existing file. Only the changed portion is sent, making edits easier to review than full file rewrites.

Inputs

file_path

string

required

Absolute path to the file to edit.

old_string

string

required

The exact text to replace. Must appear in the file and must be unique unless replace_all is set to true. Include enough surrounding context (typically 2–4 lines) to uniquely identify the target location.

new_string

string

required

The text to replace old_string with. Must be different from old_string.

replace_all

boolean

When true, replaces all occurrences of old_string in the file. Defaults to false. Use this when renaming a variable or making the same change in multiple places.

Output

Returns the file path, the old and new strings, and a structured diff patch showing the changes.

Notes

Claude must read the file with Read before calling Edit. The tool fails if no prior Read occurred in the conversation.
The edit fails if old_string is not found in the file, or if it appears more than once and replace_all is false.
Indentation must match exactly as it appears in the file — do not include line number prefixes from Read output in old_string or new_string.

Example

Edit:
  file_path: /home/user/project/src/auth.ts
  old_string: |
    function login(user: string) {
      return fetch('/api/login', { method: 'POST' })
  new_string: |
    async function login(user: string) {
      return await fetch('/api/login', { method: 'POST' })

Glob

Finds files matching a glob pattern. Returns results sorted by modification time (most recently modified first).

Inputs

pattern

string

required

The glob pattern to match files against. Supports standard glob syntax including ** for recursive matching.

path

string

Directory to search in. Defaults to the current working directory. Must be a valid directory path if provided — do not pass "undefined" or "null".

Output

filenames

string[]

Array of file paths matching the pattern, relative to the search directory.

numFiles

number

Total number of files found.

truncated

boolean

true if results were truncated to 100 files.

durationMs

number

Time taken to execute the search in milliseconds.

Notes

Results are capped at 100 files. If results are truncated, narrow the pattern.
For open-ended searches that may require multiple rounds of globbing and grepping, use the Agent tool instead.

Example

Glob:
  pattern: "src/**/*.ts"
  path: /home/user/project

Grep

Searches file contents using ripgrep with full regex support. Returns file paths with matches, matching lines, or match counts depending on the output mode.

Inputs

pattern

string

required

The regular expression pattern to search for. Uses ripgrep regex syntax. Literal braces must be escaped (for example, use interface\{\} to find interface{} in Go code).

path

string

File or directory to search. Defaults to the current working directory.

glob

string

Glob pattern to filter which files are searched (for example, "*.ts" or "*.{ts,tsx}"). Maps to rg --glob.

output_mode

string

Controls what is returned. Options:

"files_with_matches" (default) — returns only the paths of files containing matches
"content" — returns matching lines with optional context lines
"count" — returns match counts per file

-B

number

Lines of context before each match. Only applies when output_mode is "content".

-A

number

Lines of context after each match. Only applies when output_mode is "content".

-C

number

Lines of context before and after each match. Only applies when output_mode is "content".

multiline

boolean

When true, allows patterns to match across multiple lines. Required for patterns like struct \{[\s\S]*?field. Defaults to false.

Output

Depends on output_mode:

files_with_matches — list of file paths
content — matching lines with file path, line number, and optional context
count — number of matches per file

Notes

Always use Grep for content searches instead of invoking grep or rg through Bash. The Grep tool handles permissions and access correctly.
For open-ended searches requiring multiple rounds, use the Agent tool.

Example

Grep:
  pattern: "useEffect\\("
  path: /home/user/project/src
  glob: "*.tsx"
  output_mode: "content"
  -B: 2
  -A: 5

Commands

Tools

Read

Inputs

Output

Notes

Example

Write

Inputs

Output

Notes

Example

Edit

Inputs

Output

Notes

Example

Glob

Inputs

Output

Notes

Example

Grep

Inputs

Output

Notes

Example

Build docs developers (and LLMs) love

Commands

Tools

​Read

​Inputs

​Output

​Notes

​Example

​Write

​Inputs

​Output

​Notes

​Example

​Edit

​Inputs

​Output

​Notes

​Example

​Glob

​Inputs

​Output

​Notes

​Example

​Grep

​Inputs

​Output

​Notes

​Example

Build docs developers (and LLMs) love

Read

Inputs

Output

Notes

Example

Write

Inputs

Output

Notes

Example

Edit

Inputs

Output

Notes

Example

Glob

Inputs

Output

Notes

Example

Grep

Inputs

Output

Notes

Example