> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.

# File operation tools

> Reference for the Read, Write, Edit, Glob, and Grep tools that Claude uses to work with files on the local filesystem.

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

<ParamField body="file_path" type="string" required>
  Absolute path to the file to read.
</ParamField>

<ParamField body="offset" type="number">
  Line number to start reading from (1-indexed). Use this with `limit` to read a specific section of a large file.
</ParamField>

<ParamField body="limit" type="number">
  Maximum number of lines to read. Defaults to 2,000. Combine with `offset` to page through large files.
</ParamField>

<ParamField body="pages" type="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.
</ParamField>

### 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

```text theme={null}
Read:
  file_path: /home/user/project/src/index.ts
  offset: 100
  limit: 50
```

***

## Write

Creates or overwrites a file on the local filesystem.

<Warning>
  `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.
</Warning>

### Inputs

<ParamField body="file_path" type="string" required>
  Absolute path to the file to write. Intermediate directories are not created automatically — use `Bash` with `mkdir -p` first if needed.
</ParamField>

<ParamField body="content" type="string" required>
  The full content to write to the file.
</ParamField>

### 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

```text theme={null}
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

<ParamField body="file_path" type="string" required>
  Absolute path to the file to edit.
</ParamField>

<ParamField body="old_string" type="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.
</ParamField>

<ParamField body="new_string" type="string" required>
  The text to replace `old_string` with. Must be different from `old_string`.
</ParamField>

<ParamField body="replace_all" type="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.
</ParamField>

### 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

```text theme={null}
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

<ParamField body="pattern" type="string" required>
  The glob pattern to match files against. Supports standard glob syntax including `**` for recursive matching.
</ParamField>

<ParamField body="path" type="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"`.
</ParamField>

### Output

<ResponseField name="filenames" type="string[]">
  Array of file paths matching the pattern, relative to the search directory.
</ResponseField>

<ResponseField name="numFiles" type="number">
  Total number of files found.
</ResponseField>

<ResponseField name="truncated" type="boolean">
  `true` if results were truncated to 100 files.
</ResponseField>

<ResponseField name="durationMs" type="number">
  Time taken to execute the search in milliseconds.
</ResponseField>

### 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

```text theme={null}
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

<ParamField body="pattern" type="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).
</ParamField>

<ParamField body="path" type="string">
  File or directory to search. Defaults to the current working directory.
</ParamField>

<ParamField body="glob" type="string">
  Glob pattern to filter which files are searched (for example, `"*.ts"` or `"*.{ts,tsx}"`). Maps to `rg --glob`.
</ParamField>

<ParamField body="output_mode" type="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
</ParamField>

<ParamField body="-B" type="number">
  Lines of context before each match. Only applies when `output_mode` is `"content"`.
</ParamField>

<ParamField body="-A" type="number">
  Lines of context after each match. Only applies when `output_mode` is `"content"`.
</ParamField>

<ParamField body="-C" type="number">
  Lines of context before and after each match. Only applies when `output_mode` is `"content"`.
</ParamField>

<ParamField body="multiline" type="boolean">
  When `true`, allows patterns to match across multiple lines. Required for patterns like `struct \{[\s\S]*?field`. Defaults to `false`.
</ParamField>

### 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

```text theme={null}
Grep:
  pattern: "useEffect\\("
  path: /home/user/project/src
  glob: "*.tsx"
  output_mode: "content"
  -B: 2
  -A: 5
```