Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us