AI Assistant

File Tools

Claude Code provides six tools for interacting with the filesystem: reading, writing, editing files, searching file contents, finding files by pattern, and editing Jupyter notebooks.

FileReadTool (Read)

Reads files from the local filesystem with support for text files, images, PDFs, and Jupyter notebooks.

Parameters

file_pathstringrequired

Absolute path to the file to read.

offsetnumber

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

limitnumber

Number of lines to read. Defaults to 2000 lines from the beginning of the file.

pagesstring

Page range for PDF files (e.g., "1-5", "3", "10-20"). Required for PDFs over 10 pages. Maximum 20 pages per request.

Behavior

  • Text files: Returns content with line numbers in cat -n format
  • Images: Renders the image visually (Claude is multimodal)
  • PDFs: Extracts text content, with a page limit per request
  • Jupyter notebooks: Returns all cells with their outputs, combining code, text, and visualizations
  • Binary files: Detected by extension and rejected with an appropriate error

Results are returned with line numbers starting at 1. The default read limit is 2000 lines. For large files, use offset and limit to read specific sections.

Security

  • Blocks reads from dangerous device paths (/dev/zero, /dev/random, /dev/stdin, etc.) to prevent hanging
  • Skips filesystem operations for UNC paths on Windows to prevent NTLM credential leaks
  • Respects file read token and size limits from the ToolUseContext

Key Properties

  • Read-only: Yes
  • Concurrency-safe: Yes
  • maxResultSizeChars: Infinity (output is never persisted to disk to avoid circular Read loops)

FileEditTool (Edit)

Performs exact string replacements in files. The primary tool for making targeted code changes.

Parameters

file_pathstringrequired

Absolute path to the file to modify.

old_stringstringrequired

The exact text to find and replace. Must be unique in the file or the edit will fail.

new_stringstringrequired

The replacement text. Must differ from old_string.

replace_allboolean

When true, replaces all occurrences of old_string. Default: false.

Behavior

  • Requires old_string to be unique in the file (unless replace_all is true)
  • Preserves line endings (CRLF/LF) from the original file
  • Tracks file modifications for attribution and history
  • Notifies LSP servers and VS Code of file changes

Staleness Detection

FileEditTool implements staleness detection to prevent edits to files that have been modified since they were last read:

  1. When a file is read (via FileReadTool or FileEditTool), its modification time is cached in readFileState
  2. Before applying an edit, the tool checks if the file's current modification time matches the cached value
  3. If the file was modified externally (by another process, user, or tool), the edit fails with FILE_UNEXPECTEDLY_MODIFIED_ERROR

Files larger than 1 GiB (1,073,741,824 bytes) cannot be edited. This limit prevents out-of-memory crashes from V8/Bun's string length limit of approximately 2^30 characters.

Key Properties

  • Read-only: No
  • Concurrency-safe: No
  • maxResultSizeChars: 100,000
  • Strict mode: Yes

FileWriteTool (Write)

Creates new files or completely overwrites existing files.

Parameters

file_pathstringrequired

Absolute path to the file to write.

contentstringrequired

The complete content to write to the file.

Behavior

  • Creates parent directories if they do not exist
  • For existing files, records a diff between old and new content
  • Tracks file modifications for git attribution
  • Returns whether the operation was a create or update

Key Properties

  • Read-only: No
  • Concurrency-safe: No
  • maxResultSizeChars: 100,000
  • Strict mode: Yes

GlobTool (Glob)

Fast file pattern matching using glob patterns. Works efficiently with codebases of any size.

Parameters

patternstringrequired

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

pathstring

Directory to search in. Defaults to the current working directory if omitted.

Behavior

  • Returns matching file paths sorted by modification time
  • Results are limited (truncated flag set when exceeded)
  • Validates that the provided path exists and is a directory

Key Properties

  • Read-only: Yes
  • Concurrency-safe: Yes
  • maxResultSizeChars: 100,000

GrepTool (Grep)

Searches file contents using regular expressions, powered by ripgrep (rg).

Parameters

patternstringrequired

Regular expression pattern to search for. Supports full regex syntax.

pathstring

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

globstring

Glob pattern to filter searched files (e.g., "*.js", "*.{ts,tsx}"). Maps to rg --glob.

typestring

File type filter (e.g., "js", "py", "rust"). Maps to rg --type. More efficient than glob for standard file types.

output_modestring

Output format. One of: "content" (matching lines), "files_with_matches" (file paths, default), "count" (match counts).

-Anumber

Lines to show after each match. Only used in content mode.

-Bnumber

Lines to show before each match. Only used in content mode.

-C / contextnumber

Lines to show before and after each match. Only used in content mode.

-nboolean

Show line numbers. Defaults to true in content mode.

-iboolean

Case-insensitive search.

head_limitnumber

Limit output to first N entries. Defaults to 250. Pass 0 for unlimited.

offsetnumber

Skip first N entries before applying head_limit. Enables pagination.

multilineboolean

Enable multiline mode where . matches newlines and patterns can span lines. Maps to rg -U --multiline-dotall.

Behavior

  • Automatically excludes version control directories (.git, .svn, .hg, .bzr, .jj, .sl)
  • Default head_limit of 250 prevents context bloat from unbounded searches
  • When truncation occurs, appliedLimit is set in the output so the model can paginate with offset

Key Properties

  • Read-only: Yes
  • Concurrency-safe: Yes
  • maxResultSizeChars: 20,000

NotebookEditTool (NotebookEdit)

Edits Jupyter notebook (.ipynb) cells.

Parameters

notebook_pathstringrequired

Absolute path to the Jupyter notebook file.

cell_idstring

ID of the cell to edit. For inserts, the new cell is placed after this cell. Omit to insert at the beginning.

new_sourcestringrequired

The new source content for the cell.

cell_typestring

Cell type: "code" or "markdown". Defaults to the current cell's type for replace operations. Required for insert.

edit_modestring

Edit operation: "replace" (default), "insert", or "delete".

Key Properties

  • Read-only: No
  • Concurrency-safe: No
  • Deferred: Yes (requires ToolSearch to use)
  • maxResultSizeChars: 100,000

Key Source Files

  • src/tools/FileReadTool/FileReadTool.ts: FileRead implementation
  • src/tools/FileEditTool/FileEditTool.ts: FileEdit with staleness detection
  • src/tools/FileWriteTool/FileWriteTool.ts: FileWrite implementation
  • src/tools/GlobTool/GlobTool.ts: Glob pattern matching
  • src/tools/GrepTool/GrepTool.ts: Ripgrep-powered search
  • src/tools/NotebookEditTool/NotebookEditTool.ts: Jupyter notebook editing
Tools Overview PreviousShell ToolsNext