Skip to main content

​
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).
{
  "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.
{
  "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.
{
  "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).

Git Operations

Stage and commit file changes with git tools.

Code Analysis

Lint and type-check after editing files.