> ## 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.

# 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**

<ParamField path="path" type="string" required>
  Path to the file to read
</ParamField>

<ParamField path="offset" type="integer">
  Line number to start reading from (1-indexed, optional)
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of lines to read (optional)
</ParamField>

**Output**

<ResponseField name="content" type="string">
  File content with line numbers formatted as `line_num│ content`
</ResponseField>

<ResponseField name="total_lines" type="integer">
  Total number of lines in the file
</ResponseField>

<ResponseField name="lines_shown" type="integer">
  Number of lines returned in this response
</ResponseField>

<ResponseField name="path" type="string">
  Absolute path to the file that was read
</ResponseField>

**Example**

```json theme={null}
{
  "path": "src/main.rs",
  "offset": 10,
  "limit": 20
}
```

**Response**

```json theme={null}
{
  "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.

<Warning>
  Not for workspace memory files like `HEARTBEAT.md`, `MEMORY.md`, etc. Use `memory_write` for those.
</Warning>

**Input Parameters**

<ParamField path="path" type="string" required>
  Path to the file to write
</ParamField>

<ParamField path="content" type="string" required>
  Content to write to the file
</ParamField>

**Output**

<ResponseField name="path" type="string">
  Absolute path to the file that was written
</ResponseField>

<ResponseField name="bytes_written" type="integer">
  Number of bytes written
</ResponseField>

<ResponseField name="success" type="boolean">
  Always true on successful write
</ResponseField>

**Example**

```json theme={null}
{
  "path": "output.txt",
  "content": "Hello, World!"
}
```

**Response**

```json theme={null}
{
  "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**

<ParamField path="path" type="string" default=".">
  Path to the directory to list (defaults to current directory)
</ParamField>

<ParamField path="recursive" type="boolean" default={false}>
  If true, list contents recursively
</ParamField>

<ParamField path="max_depth" type="integer" default={3}>
  Maximum depth for recursive listing
</ParamField>

**Output**

<ResponseField name="path" type="string">
  Absolute path to the directory that was listed
</ResponseField>

<ResponseField name="entries" type="array">
  Array of entry strings. Directories end with `/`, files show size in parentheses
</ResponseField>

<ResponseField name="count" type="integer">
  Number of entries returned
</ResponseField>

<ResponseField name="truncated" type="boolean">
  True if results were truncated (max 500 entries)
</ResponseField>

**Example**

```json theme={null}
{
  "path": "src",
  "recursive": true,
  "max_depth": 2
}
```

**Response**

```json theme={null}
{
  "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.

<Note>
  The `old_string` must match exactly, including whitespace and indentation.
</Note>

**Input Parameters**

<ParamField path="path" type="string" required>
  Path to the file to edit
</ParamField>

<ParamField path="old_string" type="string" required>
  The exact string to find and replace
</ParamField>

<ParamField path="new_string" type="string" required>
  The string to replace it with
</ParamField>

<ParamField path="replace_all" type="boolean" default={false}>
  If true, replace all occurrences. If false, replaces first occurrence only.
</ParamField>

**Output**

<ResponseField name="path" type="string">
  Absolute path to the file that was edited
</ResponseField>

<ResponseField name="replacements" type="integer">
  Number of replacements made
</ResponseField>

<ResponseField name="success" type="boolean">
  Always true on successful patch
</ResponseField>

**Example**

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

**Response**

```json theme={null}
{
  "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