Skip to main content
Filesystem tools provide safe file operations with workspace restrictions and size limits.

​
read_file

Read the contents of a file at the given path.

​
Parameters

​
path
string
required
The file path to read (relative to workspace or absolute)

​
Return Value

Returns the file contents as a string, or an error message if:
  • File not found
  • Path is not a file
  • File is too large (>512 KB)
  • Permission denied
Output is truncated to 128,000 characters if the file is larger.

​
Example

{
  "path": "src/config.json"
}
Returns: 
{
  "apiKey": "...",
  "timeout": 30
}

​
write_file

Write content to a file at the given path. Creates parent directories if needed.

​
Parameters

​
path
string
required
The file path to write to
​
content
string
required
The content to write to the file

​
Return Value

Returns a success message with the number of bytes written, or an error message.

​
Example

{
  "path": "output/result.txt",
  "content": "Processing complete\n"
}
Returns: 
Successfully wrote 20 bytes to /workspace/output/result.txt

​
edit_file

Edit a file by replacing exact text matches. The old_text must exist exactly in the file.

​
Parameters

​
path
string
required
The file path to edit
​
old_text
string
required
The exact text to find and replace (must match exactly)
​
new_text
string
required
The text to replace with

​
Return Value

Returns a success message, or an error if:
  • File not found
  • old_text not found in file (includes diff of closest match)
  • old_text appears multiple times (requires more context)

​
Example

{
  "path": "config.py",
  "old_text": "timeout = 30",
  "new_text": "timeout = 60"
}
Returns: 
Successfully edited /workspace/config.py

​
Error: Text Not Found

{
  "path": "config.py",
  "old_text": "timeout = 10",
  "new_text": "timeout = 60"
}
Returns: 
Error: old_text not found in config.py.
Best match (85% similar) at line 42:
--- old_text (provided)
+++ config.py (actual, line 42)
@@ -1 +1 @@
-timeout = 10
+timeout = 30

​
Error: Multiple Matches

{
  "path": "config.py",
  "old_text": "timeout",
  "new_text": "delay"
}
Returns: 
Warning: old_text appears 5 times. Please provide more context to make it unique.

​
list_dir

List the contents of a directory.

​
Parameters

​
path
string
required
The directory path to list

​
Return Value

Returns a formatted list of directory contents with file/folder indicators, or an error message.

​
Example

{
  "path": "src"
}
Returns: 
📁 components
📁 utils
📄 main.py
📄 config.py
📄 __init__.py

​
Configuration

All filesystem tools can be configured with: 
ReadFileTool(workspace=Path("/workspace"), allowed_dir=Path("/workspace"))
WriteFileTool(workspace=Path("/workspace"), allowed_dir=Path("/workspace"))
EditFileTool(workspace=Path("/workspace"), allowed_dir=Path("/workspace"))
ListDirTool(workspace=Path("/workspace"), allowed_dir=Path("/workspace"))
  • workspace: Base directory for resolving relative paths
  • allowed_dir: If set, restricts all operations to this directory tree

​
Path Resolution

Paths are resolved with the following rules:
  1. Expand user home directory (~)
  2. If relative, resolve against workspace
  3. Resolve to absolute path
  4. If allowed_dir is set, verify path is within allowed directory
Attempts to access files outside the allowed directory return a PermissionError.

​
Size Limits

  • read_file: Maximum 128,000 characters (files up to ~512 KB)
  • Larger files return an error suggesting use of exec tool with head, tail, or grep

​
Implementation

See nanobot/agent/tools/filesystem.py for full implementations:
  • ReadFileTool: line 26
  • WriteFileTool: line 76
  • EditFileTool: line 114
  • ListDirTool: line 195
  • Shell Tool - Execute shell commands for advanced file operations

Build docs developers (and LLMs) love

Get started for freeTalk to us