File Tools

Read, Edit, Write, Glob, and Grep — the tools Claude Code uses to work with files and search codebases.

Claude Code includes five dedicated file tools. Using these tools is always preferred over running equivalent shell commands (cat, grep, find, sed) because they carry better permission semantics and produce a clearer activity trail.

---

Read

Reads a file from the local filesystem. Supports text files, images (PNG, JPG, GIF, WebP), PDF documents, and Jupyter notebooks (.ipynb).

Parameters

file_path · string · required

Absolute path to the file to read. Relative paths are not accepted.

offset · number

Line number to start reading from (1-indexed). Only provide when the file is too large to read at once.

limit · number

Number of lines to read. Only provide when the file is too large to read at once.

pages · string

Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum 20 pages per request.

Output

The output format depends on the file type.

Text

type · string

"text"

file · object

Show properties

filePath · string

Path to the file that was read.

content · string

File content with line numbers prefixed in cat -n format.

numLines · number

Number of lines in the returned content.

startLine · number

The starting line number (matches offset).

totalLines · number

Total number of lines in the file.

Image

type · string

"image"

file · object

Show properties

base64 · string

Base64-encoded image data.

type · string

MIME type: image/jpeg, image/png, image/gif, or image/webp.

originalSize · number

Original file size in bytes.

dimensions · object

Optional dimension info (originalWidth, originalHeight, displayWidth, displayHeight).

PDF

type · string

"pdf" or "parts" (when pages are extracted as images)

file · object

Show properties

filePath · string

Path to the PDF file.

base64 · string

Base64-encoded PDF data (type pdf).

originalSize · number

Original file size in bytes.

count · number

Number of pages extracted (type parts).

outputDir · string

Directory containing extracted page images (type parts).

Notebook

type · string

"notebook"

file · object

Show properties

filePath · string

Path to the notebook file.

cells · array

Array of notebook cells with their outputs.

Usage notes

• By default, reads up to 2000 lines from the beginning of the file.
• For large files, use offset and limit to read specific sections.
• Images are automatically resized if they would exceed the token budget.
• For PDFs with more than 10 pages, you must provide the pages parameter.
• If the same file is read again without modification, Claude Code returns a file_unchanged stub to avoid duplicating content in context.

Examples

Reading a source file

file_path: "/home/user/project/src/index.ts"

Reading 100–150 of a large file

file_path: "/home/user/project/logs/app.log"
offset: 100
limit: 50

Reading pages 1–5 of a PDF

file_path: "/home/user/docs/report.pdf"
pages: "1-5"

---

Edit

Performs an exact string replacement in an existing file. The file must have been read with Read before it can be edited.

Parameters

file_path · string · required

Absolute path to the file to modify.

old_string · string · required

The exact text to find and replace. Must be unique in the file unless replace_all is true.

new_string · string · required

The replacement text. Must differ from old_string.

replace_all · boolean · default: "false"

When true, replaces every occurrence of old_string. Useful for renaming variables or symbols across a file.

Output

filePath · string

Path to the file that was updated.

oldString · string

The actual string that was replaced (may differ from input after quote normalization).

newString · string

The replacement string.

structuredPatch · array

Diff patch showing the changes as hunks.

replaceAll · boolean

Whether all occurrences were replaced.

Usage notes

• You must call Read on the file before calling Edit.
• The edit fails if old_string appears more than once in the file and replace_all is false. Provide more surrounding context to make the match unique.
• Preserve exact indentation from the Read output. The line number prefix (e.g., 1→) is not part of the file content and must not be included in old_string or new_string.
• Use replace_all: true for renames and find-and-replace operations across the entire file.
• Cannot edit Jupyter notebooks (.ipynb); use the NotebookEdit tool instead.

Edit will fail if the file has been modified since it was last read. Read the file again to get the current content before retrying.

Example

Rename a function

file_path: "/home/user/project/src/utils.ts"
old_string: "function calculateTotal("
new_string: "function computeTotal("
replace_all: true

---

Write

Creates a new file or completely overwrites an existing file. For modifying existing files, prefer Edit — it sends only the diff and is more efficient.

Parameters

file_path · string · required

Absolute path to the file to write. Must be an absolute path.

content · string · required

The full content to write to the file.

Output

type · string

"create" for new files, "update" for overwritten files.

filePath · string

Path to the file that was written.

content · string

The content that was written.

structuredPatch · array

Diff patch for updates (empty for new file creation).

originalFile · string

The original file content before the write. null for new files.

Usage notes

• If the file already exists, it must have been read first with Read.
• The tool creates any missing parent directories automatically.
• Use Edit when only modifying part of an existing file — Write sends the entire file content every time.

Do not use Write to create documentation files (.md, README) unless explicitly requested.

Example

Create a new configuration file

file_path: "/home/user/project/.eslintrc.json"
content: |
  {
    "extends": "eslint:recommended",
    "rules": {
      "no-console": "warn"
    }
  }

---

Glob

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

Parameters

pattern · string · required

Glob pattern to match files against (e.g., "**/*.ts", "src/**/*.{ts,tsx}").

path · string

Directory to search in. Defaults to the current working directory. Omit entirely to use the default — do not pass "undefined" or "null".

Output

filenames · string[]

Array of matching file paths (relative to cwd).

numFiles · number

Total number of files found.

durationMs · number

Time taken to execute the search in milliseconds.

truncated · boolean

Whether results were capped at 100 files. Use a more specific pattern or path if truncated.

Usage notes

• Supports standard glob syntax: *, **, ?, {a,b}, [abc].
• Use Glob instead of running find or ls via Bash.
• Results are capped at 100 files. Narrow the pattern or set path to a subdirectory if you hit the limit.

Examples

Find all TypeScript files

pattern: "**/*.ts"

Find test files in a specific directory

pattern: "**/*.test.{ts,tsx}"
path: "/home/user/project/src"

---

Grep

Searches file contents using regular expressions. Powered by ripgrep for fast, accurate searches across large codebases.

Parameters

pattern · string · required

Regular expression pattern to search for in file contents. Uses ripgrep syntax — literal braces must be escaped (e.g., use interface\{\} to match interface{}).

path · string

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

glob · string

Glob pattern to filter which files are searched (e.g., "*.js", "*.{ts,tsx}"). Maps to ripgrep’s --glob flag.

output_mode · string · default: "files_with_matches"

Controls output format:

• "files_with_matches" — returns file paths only (default)
• "content" — returns matching lines with context
• "count" — returns match counts per file

-B · number

Lines of context to show before each match. Requires output_mode: "content".

-A · number

Lines of context to show after each match. Requires output_mode: "content".

-C · number

Lines of context to show both before and after each match (alias for context). Requires output_mode: "content".

context · number

Lines to show before and after each match. Equivalent to -C. Requires output_mode: "content".

-n · boolean · default: "true"

Show line numbers in output. Requires output_mode: "content".

-i · boolean · default: "false"

Case-insensitive search.

type · string

File type filter using ripgrep type names (e.g., "js", "py", "rust", "go"). More efficient than glob for standard language types.

head_limit · number · default: "250"

Limit output to the first N results, equivalent to piping through head -N. Pass 0 for unlimited results (use sparingly).

offset · number · default: "0"

Skip the first N results before applying head_limit. Useful for paginating through large result sets.

multiline · boolean · default: "false"

Enable multiline mode where . matches newlines and patterns can span multiple lines. Maps to ripgrep’s -U --multiline-dotall.

Output

mode · string

The output mode that was used.

filenames · string[]

Matching file paths (populated in files_with_matches mode).

numFiles · number

Number of files with matches.

content · string

Matching lines or counts as a string (populated in content and count modes).

numLines · number

Number of output lines (content mode only).

numMatches · number

Total match count across all files (count mode only).

appliedLimit · number

The limit that was applied when results were truncated.

appliedOffset · number

The offset that was applied.

Usage notes

• Always prefer Grep over running grep or rg via Bash.
• VCS directories (.git, .svn, .hg) are automatically excluded.
• Lines longer than 500 characters are truncated to avoid base64 or minified content cluttering results.
• Results in files_with_matches mode are sorted by modification time (most recently modified first).

Examples

Find files containing a function name

pattern: "function calculateTotal"
output_mode: "files_with_matches"

Search TypeScript files with context

pattern: "TODO|FIXME"
type: "ts"
output_mode: "content"
-C: 2

Case-insensitive search with line numbers

pattern: "error handling"
path: "/home/user/project/src"
output_mode: "content"
-i: true

Count occurrences per file

pattern: "console\\.log"
output_mode: "count"
glob: "*.js"