Filesystem tools

Read, write, search, and manipulate files and directories

Filesystem tools provide comprehensive file and directory operations. Tools are organized by operation type: navigation, read, search, and write.

Tool organization

All filesystem tools are accessed through the fs namespace:

import { fs } from "@/core/agent/tools/fs";

// Navigation tools
const pwdTool = fs.pwd();
const cdTool = fs.cd();
const lsTool = fs.ls();

// Read tools
const readTool = fs.read();
const headTool = fs.head();

// Search tools
const grepTool = fs.grep();
const findTool = fs.find();

// Write tools (approval required)
const writeTools = fs.write();
yield* registerTool(writeTools.approval);
yield* registerTool(writeTools.execute);

Navigation tools

pwd

Get the current working directory.

Parameters: None

Returns:

path · string

Current working directory path

Example:

const result = yield* pwdTool.handler({}, context);
// { success: true, result: { path: "/home/user/project" } }

cd

Change the current working directory.

Parameters:

path · string · required

Target directory path (relative or absolute)

Returns:

path · string

New working directory path

ls

List directory contents with filtering and recursion.

Parameters:

path · string

Directory path (defaults to current working directory)

showHidden · boolean · default: false

Include hidden files (starting with .)

recursive · boolean · default: false

Recurse into subdirectories

pattern · string

Name filter. Supports:

• Substring match: "test"
• Regex: "re:test.*\\.ts$"

maxResults · number · default: 200

Maximum results (cap: 2000)

maxDepth · number · default: 10

Maximum depth for recursive listing

Returns:

Array of entries:

path · string

Full path to file or directory

name · string

File or directory name

type · 'file' | 'dir'

Entry type

Example:

const result = yield* lsTool.handler(
  {
    path: "src",
    recursive: true,
    pattern: "*.ts",
    maxResults: 100,
  },
  context
);

stat

Get file or directory metadata.

Parameters:

path · string · required

File or directory path

Returns:

type · 'File' | 'Directory' | 'SymbolicLink'

Entry type

size · number

Size in bytes

mtime · number

Last modified time (milliseconds since epoch)

Read tools

read_file

Read file contents with optional line range filtering.

Parameters:

path · string · required

File path to read

startLine · number

1-based start line (inclusive)

endLine · number

1-based end line (inclusive)

maxBytes · number · default: 131072

Maximum bytes to return (cap: 524288 = 512KB)

encoding · string · default: "utf-8"

Text encoding

Returns:

path · string

Resolved file path

content · string

File contents

encoding · string

Encoding used

truncated · boolean

Whether output was truncated

totalLines · number

Total lines in file

returnedLines · number

Lines returned

range · object

Line range if specified:

Show properties

startLine · number

Start line (1-based)

endLine · number

End line (1-based)

Example:

// Read entire file
const result1 = yield* readTool.handler({ path: "src/main.ts" }, context);

// Read specific lines
const result2 = yield* readTool.handler(
  {
    path: "src/main.ts",
    startLine: 10,
    endLine: 50,
  },
  context
);

head

Read first N lines of a file.

Parameters:

path · string · required

File path

lines · number · default: 10

Number of lines to read

tail

Read last N lines of a file.

Parameters:

path · string · required

File path

lines · number · default: 10

Number of lines to read

readPdf

Read PDF file contents.

Parameters:

path · string · required

PDF file path

pages · number[]

Specific pages to extract (1-based)

Returns:

text · string

Extracted text content

totalPages · number

Total pages in PDF

pdfPageCount

Get total page count of a PDF file.

Parameters:

path · string · required

PDF file path

Returns:

pageCount · number

Total pages

Search tools

grep

Search file contents using text patterns or regex. Uses ripgrep when available, falls back to system grep.

Parameters:

pattern · string · required

Search pattern. Supports:

• Literal text: "error"
• Regex: "re:error.*\\d+"

path · string

Path to search (defaults to current working directory)

recursive · boolean · default: true

Recurse into subdirectories

regex · boolean · default: false

Treat pattern as regex

ignoreCase · boolean · default: false

Case-insensitive matching

maxResults · number · default: 200

Maximum matches (cap: 2000)

filePattern · string

File glob filter (e.g., "*.ts", "*.{js,jsx}")

exclude · string

Exclude files matching pattern

excludeDir · string

Exclude directories matching pattern

contextLines · number · default: 0

Context lines above/below each match

outputMode · 'content' | 'files' | 'count' · default: "content"

Output format:

• content: Show matching lines with line numbers
• files: Show only file paths
• count: Show match counts per file

Returns:

pattern · string

Search pattern used

searchPath · string

Path searched

backend · 'ripgrep' | 'grep'

Backend used for search

outputMode · string

Output mode used

matches · array

Matches found (when outputMode: 'content'):

Show Match object

file · string

File path

line · number

Line number

text · string

Matching line text

files · string[]

File paths (when outputMode: 'files')

counts · array

Match counts (when outputMode: 'count'):

Show Count object

file · string

File path

count · number

Number of matches

totalFound · number

Total results found

Example:

// Search for error messages in TypeScript files
const result = yield* grepTool.handler(
  {
    pattern: "re:error.*\\d+",
    regex: true,
    filePattern: "*.ts",
    contextLines: 2,
    maxResults: 100,
  },
  context
);

find

Find files and directories by name, glob, or regex. Uses fast-glob by default, falls back to fd/find for advanced filters.

Parameters:

path · string

Start directory. Omit for smart hierarchical search (cwd → parents → home)

name · string

Name filter. Supports:

• Substring: "test"
• Glob: "*.ts", "**/*.test.ts"
• Regex: "re:test.*\\.ts$"

type · 'file' | 'dir' | 'all' | 'symlink' · default: "all"

Type filter

maxDepth · number · default: 25

Maximum depth (0 = current directory only)

minDepth · number · default: 0

Minimum depth (triggers fd/find backend)

maxResults · number · default: 200

Maximum results (cap: 2000)

includeHidden · boolean · default: false

Include hidden files and directories

smart · boolean · default: true

Smart hierarchical search. Disable when providing specific path

pathPattern · string

Full-path pattern (e.g., "**/test/**"). Triggers fd/find backend

excludePaths · string[]

Paths to exclude. Triggers fd/find backend

caseSensitive · boolean · default: false

Case-sensitive matching

size · string

Size filter (e.g., "+100M", "-1k"). Triggers fd/find backend

mtime · string

Modification time filter:

• "-7": Last 7 days
• "+30": Older than 30 days

Triggers fd/find backend

Returns:

Array of entries:

path · string

Full path

name · string

File or directory name

type · 'file' | 'dir' | 'symlink'

Entry type

Example:

// Find TypeScript test files modified in last 7 days
const result = yield* findTool.handler(
  {
    name: "*.test.ts",
    mtime: "-7",
    maxResults: 50,
  },
  context
);

Write tools

All write tools require user approval before execution.

write_file

Write content to a file, creating it if needed.

Parameters:

path · string · required

File path (created if doesn’t exist)

content · string · required

Full file content (replaces existing content)

encoding · string · default: "utf-8"

Text encoding

createDirs · boolean · default: false

Create parent directories if missing

Returns:

path · string

Written file path

message · string

Success message

isNewFile · boolean

Whether file was newly created

diff · string

Unified diff showing changes

edit_file

Edit specific parts of a file using structured operations.

Parameters:

path · string · required

File path (must exist)

edits · array · required

Edit operations to apply in order. Each operation is one of:

Show replace_lines

Replace a range of lines:

type · 'replace_lines' · required

startLine · number · required

Start line (1-based)

endLine · number · required

End line (1-based)

content · string · required

Replacement content

Show replace_pattern

Find and replace text patterns:

type · 'replace_pattern' · required

pattern · string · required

Pattern to find. Supports:

• Literal: "oldText"
• Regex: "re:old.*Text"

Only for simple bulk find-and-replace (e.g., renaming variables). Use replace_lines for structural edits

replacement · string · required

Replacement text

count · number · default: 1

Matches to replace:

• 1: First match only (default)
• -1: All matches
• n: First n matches

Show insert

Insert content at a specific line:

type · 'insert' · required

line · number · required

Insert after this line (0 = before first line)

content · string · required

Content to insert

Show delete_lines

Delete a range of lines:

type · 'delete_lines' · required

startLine · number · required

Start line (1-based)

endLine · number · required

End line (1-based)

encoding · string · default: "utf-8"

Text encoding

Returns:

path · string

Edited file path

editsApplied · string[]

Descriptions of applied edits

totalEdits · number

Total edits applied

originalLines · number

Original line count

newLines · number

New line count

diff · string

Unified diff showing changes

Example:

const editTools = fs.edit();
const result = yield* editTools.execute.handler(
  {
    path: "src/main.ts",
    edits: [
      {
        type: "replace_lines",
        startLine: 5,
        endLine: 10,
        content: "// New implementation\nfunction newCode() {\n  return true;\n}",
      },
      {
        type: "replace_pattern",
        pattern: "oldVariable",
        replacement: "newVariable",
        count: -1, // Replace all
      },
    ],
  },
  context
);

Error types:

The tool returns structured errors for better handling:

• FileNotFoundError: File doesn’t exist
• FileReadError: File exists but can’t be read
• OutOfBoundsError: Line range out of bounds
• InsertOutOfBoundsError: Insert position out of bounds
• PatternNotFoundError: Pattern not found in file
• InvalidPatternError: Malformed regex pattern
• PatternTooComplexError: Pattern too complex for find-and-replace
• RegexIterationLimitError: Regex matched too many times

mkdir

Create a directory.

Parameters:

path · string · required

Directory path to create

recursive · boolean · default: false

Create parent directories if needed

rm

Remove files or directories.

Parameters:

path · string · required

File or directory path to remove

recursive · boolean · default: false

Remove directories recursively

mv

Move or rename a file or directory.

Parameters:

source · string · required

Source path

destination · string · required

Destination path

cp

Copy a file or directory.

Parameters:

source · string · required

Source path

destination · string · required

Destination path

recursive · boolean · default: false

Copy directories recursively

Best practices

Use the right search tool

• grep: Search file contents for text or patterns
• find: Search for files by name, path, or metadata

Prefer edit_file over write_file

When modifying existing files:

// Good: Modify specific parts
edit_file({
  path: "config.json",
  edits: [{ type: "replace_pattern", pattern: "old", replacement: "new" }],
});

// Bad: Replace entire file
const content = read_file({ path: "config.json" });
const modified = content.replace("old", "new");
write_file({ path: "config.json", content: modified });

Use replace_lines for structural edits

// Good: Replace specific lines
{
  type: "replace_lines",
  startLine: 10,
  endLine: 20,
  content: "new code block"
}

// Bad: Complex pattern matching for structural changes
{
  type: "replace_pattern",
  pattern: "re:function.*\\{[\\s\\S]*\\}",
  replacement: "new function"
}

Respect resource limits

Don’t request more data than needed:

// Good: Read specific line range
read_file({ path: "large-file.txt", startLine: 100, endLine: 200 });

// Bad: Read entire large file
read_file({ path: "large-file.txt" });