File Operations

File system operations for reading, writing, and navigating files

Overview

The file operations tools provide controlled access to the filesystem with path validation, sandboxing, and size limits. These tools operate on the local filesystem, not workspace memory (use memory_* tools for workspace operations).

Tools

read_file

Read a file from the local filesystem. Returns file content as text with support for partial reads.

Input Parameters

path · string · required

Path to the file to read

offset · integer

Line number to start reading from (1-indexed, optional)

limit · integer

Maximum number of lines to read (optional)

Output

content · string

File content with line numbers formatted as line_num│ content

total_lines · integer

Total number of lines in the file

lines_shown · integer

Number of lines returned in this response

path · string

Absolute path to the file that was read

Example

{
  "path": "src/main.rs",
  "offset": 10,
  "limit": 20
}

Response

{
  "content": "    10│ fn main() {\n    11│     println!(\"Hello\");",
  "total_lines": 150,
  "lines_shown": 20,
  "path": "/home/user/project/src/main.rs"
}

Constraints

• Maximum file size: 1MB
• For files larger than 1MB, use offset and limit parameters for partial reads
• Requires approval unless auto-approved
• Runs in container domain

---

write_file

Write content to a file on the local filesystem. Creates the file if it doesn’t exist, overwrites if it does. Parent directories are created automatically.

Not for workspace memory files like HEARTBEAT.md, MEMORY.md, etc. Use memory_write for those.

Input Parameters

path · string · required

Path to the file to write

content · string · required

Content to write to the file

Output

path · string

Absolute path to the file that was written

bytes_written · integer

Number of bytes written

success · boolean

Always true on successful write

Example

{
  "path": "output.txt",
  "content": "Hello, World!"
}

Response

{
  "path": "/home/user/project/output.txt",
  "bytes_written": 13,
  "success": true
}

Constraints

• Maximum content size: 5MB
• Workspace files (HEARTBEAT.md, MEMORY.md, IDENTITY.md, SOUL.md, AGENTS.md, USER.md, README.md) are rejected
• Files in daily/ or context/ directories are rejected
• Parent directories created automatically
• Rate limited: 20 calls per minute, 200 per hour

Error Conditions

• InvalidParameters: Content exceeds 5MB or path is a workspace file
• ExecutionFailed: Failed to create directories or write file

---

list_dir

List contents of a directory on the local filesystem. Shows files and subdirectories with their sizes.

Input Parameters

path · string · default: "."

Path to the directory to list (defaults to current directory)

recursive · boolean · default: false

If true, list contents recursively

max_depth · integer · default: 3

Maximum depth for recursive listing

Output

path · string

Absolute path to the directory that was listed

entries · array

Array of entry strings. Directories end with /, files show size in parentheses

count · integer

Number of entries returned

truncated · boolean

True if results were truncated (max 500 entries)

Example

{
  "path": "src",
  "recursive": true,
  "max_depth": 2
}

Response

{
  "path": "/home/user/project/src",
  "entries": [
    "tools/",
    "tools/builtin/",
    "tools/builtin/file.rs (26.3KB)",
    "tools/builtin/http.rs (28.5KB)",
    "main.rs (1.2KB)"
  ],
  "count": 5,
  "truncated": false
}

Constraints

• Maximum 500 entries returned
• Common directories excluded during recursion: node_modules, target, .git, __pycache__, venv, .venv
• Entries sorted with directories first, then alphabetically

---

apply_patch

Apply targeted edits to a file using search/replace. Finds the exact old_string and replaces it with new_string. Use for surgical code changes without rewriting entire files.

The old_string must match exactly, including whitespace and indentation.

Input Parameters

path · string · required

Path to the file to edit

old_string · string · required

The exact string to find and replace

new_string · string · required

The string to replace it with

replace_all · boolean · default: false

If true, replace all occurrences. If false, replaces first occurrence only.

Output

path · string

Absolute path to the file that was edited

replacements · integer

Number of replacements made

success · boolean

Always true on successful patch

Example

{
  "path": "src/main.rs",
  "old_string": "println!(\"old\")",
  "new_string": "println!(\"new\")",
  "replace_all": false
}

Response

{
  "path": "/home/user/project/src/main.rs",
  "replacements": 1,
  "success": true
}

Error Conditions

• ExecutionFailed: old_string not found in file (check exact match including whitespace)
• ExecutionFailed: Failed to read or write file

Constraints

• Must read file before editing
• Rate limited: 20 calls per minute, 200 per hour
• Requires approval unless auto-approved