File Operations

Read, write, edit, search, and navigate files and directories. All operations validated by FsGuard.

Overview

File operation tools give the agent read and write access to your filesystem within the configured allowed paths. Every operation passes through FsGuard - a path normalization and allowlist guard that prevents path traversal attacks and blocks access to sensitive files like .env, SSH keys, and system credentials.

Tools

read_file

Read content from a file. Supports text and binary (base64) output and partial reads by line range.

Security level: safe | Tier: Essential

path · string · required

File path to read. Can be relative (resolved against workdir) or absolute.

encoding · string · default: "utf-8"

Output encoding. Options: utf-8, base64.

lines · number

Maximum lines to read from the start (or from offset).

offset · number

Start reading from this line number (0-indexed).

Read entire file

{
  "path": "src/server.ts"
}

Limits: Files over 10MB are rejected. Blocked paths include /etc/passwd, /etc/shadow, ~/.ssh, ~/.gnupg, .env*.

---

write_file

Write content to a file. Creates new files or overwrites existing ones.

Security level: moderate | Tier: Essential

path · string · required

File path to write.

content · string · required

Content to write.

append · boolean · default: "false"

Append to end of file instead of overwriting.

createDirs · boolean · default: "false"

Create parent directories if they do not exist.

Write a new file

{
  "path": "src/utils/helpers.ts",
  "content": "export function clamp(n: number, min: number, max: number) {\n  return Math.max(min, Math.min(max, n));\n}\n"
}

---

edit_file

Surgical find-and-replace in a file. Far more efficient than rewriting entire files - only changes what’s needed.

Security level: moderate | Tier: Essential

path · string · required

File path to edit.

old_string · string · required

Exact string to find. Must be unique in the file unless replace_all is true.

new_string · string · required

Replacement string.

replace_all · boolean · default: "false"

Replace all occurrences instead of just the first.

Fix a typo

{
  "path": "src/index.ts",
  "old_string": "cosnt handler",
  "new_string": "const handler"
}

Returns a diff snippet showing the change. Fails with AMBIGUOUS_MATCH if old_string appears multiple times without replace_all.

---

search_files

Find files using glob patterns.

Security level: safe | Tier: Essential

pattern · string · required

Glob pattern (e.g., **/*.ts, src/**/*.test.ts).

directory · string

Base directory to search from. Defaults to workdir.

maxResults · number · default: "100"

Maximum files to return.

Automatically ignores node_modules/, .git/, dist/, build/.

---

grep

Search file contents using regex patterns.

Security level: safe | Tier: Essential

pattern · string · required

Regex pattern to search for (case-insensitive by default).

path · string

File or directory to search. Defaults to workdir.

glob · string

Glob filter for files (e.g., **/*.ts).

maxResults · number · default: "50"

Maximum matches to return.

context · number

Lines of context to include around each match.

Returns matches as file:line: content format.

---

directory_tree

Show the directory structure as a tree.

Security level: safe | Tier: Essential

path · string · default: "."

Root directory.

depth · number · default: "3"

Maximum depth to traverse (1-10).

include_files · boolean · default: "true"

Include files, not just directories.

pattern · string

Show only entries matching this glob (e.g., *.ts).

Auto-skips: node_modules, .git, dist, build, coverage, .next, __pycache__, .venv.

---

patch_apply

Apply a unified diff patch to a file.

Security level: moderate | Tier: Standard

path · string · required

File to patch.

patch · string · required

Unified diff content (standard git diff or diff -u format).

reverse · boolean · default: "false"

Apply patch in reverse (undo a patch).

Related Tools

Git Operations

Stage and commit file changes with git tools.

Code Analysis

Lint and type-check after editing files.