File Tools

Read

The read tool retrieves the contents of a file. It is the most frequently used tool -- the agent reads files to understand code before making changes, to check configurations, and to verify the results of edits.

Reading Text Files

By default, the read tool returns the entire file with line numbers. For large files, the agent uses offset and limit to read specific sections.

# Read the entire file
read file_path="/src/components/Header.tsx"

# Read lines 50-100
read file_path="/src/components/Header.tsx" offset=50 limit=50

Reading Images

The read tool can open image files (PNG, JPG, SVG, etc.) and present them visually to the agent. This enables the agent to analyze screenshots, design mockups, and diagram files directly.

Reading PDFs

PDF files are supported with a pages parameter to select specific page ranges. For large PDFs (more than 10 pages), the agent must specify a page range to avoid exceeding context limits.

# Read pages 1-5 of a PDF
read file_path="/docs/api-spec.pdf" pages="1-5"

Reading Jupyter Notebooks

The read tool understands .ipynb files and returns all cells with their outputs, combining code, markdown, and visualizations into a readable format.

Write

The write tool creates a new file or completely replaces the contents of an existing file. It is used when the agent needs to create new files from scratch -- components, test files, configuration files, and so on.

# Create a new component file
write file_path="/src/components/UserAvatar.tsx" content="..."

# Overwrite an existing config file
write file_path="/tsconfig.json" content="..."

Edit

The edit tool performs exact string replacement within a file. It finds an exact match of the old_string and replaces it with new_string. This is the primary tool for modifying existing code -- it is more precise and safer than rewriting entire files.

How It Works

• The agent reads the file to understand its current content.
• It identifies the exact string to replace, including surrounding context for uniqueness.
• The old_string must match exactly -- including whitespace, indentation, and line breaks.
• If old_string is not found or is not unique, the edit fails and the agent retries with a corrected match.

# Replace a specific function implementation
edit file_path="/src/utils/format.ts"
  old_string="function formatDate(date: Date): string {
  return date.toISOString();
}"
  new_string="function formatDate(date: Date): string {
  return new Intl.DateTimeFormat('en-US', {
    year: 'numeric',
    month: 'short',
    day: 'numeric',
  }).format(date);
}"

Rename with replace_all

Use the replace_all parameter to rename a variable, function, or string across an entire file.

# Rename a variable throughout a file
edit file_path="/src/config.ts"
  old_string="apiEndpoint"
  new_string="apiBaseUrl"
  replace_all=true

MultiEdit

The multiedit tool applies multiple edit operations in a single call, either to one file or across several files. This is more efficient for related changes and ensures all edits are applied atomically.

When MultiEdit Is Used

• Renaming a function and updating all its call sites across multiple files.
• Applying a consistent pattern change (e.g., updating import paths after a directory restructure).
• Making several related edits to a single file where each edit depends on the others being applied.

Each edit in the batch follows the same old_string/new_string logic as the single edit tool. If any individual edit fails (match not found), the entire batch is reported so the agent can adjust.

Glob

The glob tool finds files by pattern matching. It supports standard glob patterns and returns matching file paths sorted by modification time. This is the agent's primary tool for discovering files in your project.

Common Patterns

# Find all TypeScript files
**/*.ts

# Find test files
**/*.test.ts
**/*.spec.ts

# Find components in a specific directory
src/components/**/*.tsx

# Find configuration files
**/config.{ts,js,json}

# Find all files in a directory (one level)
src/utils/*

Grep

The grep tool searches file contents using regex patterns, powered by ripgrep under the hood. It is the agent's primary tool for finding where specific code patterns, function calls, or strings appear across your project.

Search Examples

# Find all usages of a function
grep pattern="calculateDiscount" glob="*.ts"

# Find TODO comments
grep pattern="TODO|FIXME|HACK" output_mode="content"

# Find imports of a specific module
grep pattern="from ['"]@/services/auth" glob="*.{ts,tsx}"

# Case-insensitive search with context
grep pattern="error" -i=true -C=3 path="src/middleware/"

# Count occurrences per file
grep pattern="console\.log" output_mode="count" glob="*.ts"

Ls

The ls tool lists directory contents with file metadata. It gives the agent a quick overview of a directory's structure without reading every file.

The agent typically uses ls to understand project structure before diving into specific files, or to verify that expected files exist after a write or edit operation.