File Operations
OrcBot provides cross-platform file system skills for reading, writing, and managing files. All file operations are sandboxed to the agent’s workspace to prevent accidental modification of system files.
Workspace Sandboxing
File paths are resolved relative to the build workspace:
- Default workspace:
~/.orcbot/workspace/
- Configured workspace: Set via
buildWorkspacePath in config
- Restricted paths:
node_modules and .git are blocked
Path Resolution Rules
- Absolute paths: Resolved as-is (subject to restriction checks)
- Relative paths: Resolved relative to workspace root
- Empty path (for
list_directory): Defaults to workspace root
Example:
// Input: "src/index.ts"
// Resolved: "/home/user/.orcbot/workspace/src/index.ts"
// Input: "/tmp/data.json"
// Resolved: "/tmp/data.json" (absolute path allowed)
// Input: "node_modules/package/index.js"
// Error: Access to restricted path blocked
Restricted paths are blocked. You cannot read from or write to node_modules or .git directories to prevent accidental modification of dependencies or version control.
read_file
Read the contents of a file with optional line range support.
Parameters
File path (absolute or relative to workspace)
1-based starting line number (inclusive)
1-based ending line number (inclusive)
Return Value
File contents. Truncated to 20,000 chars with instructions to use line ranges for larger files.
Limits
- Max content: 20,000 characters per response
- Line ranges: Use
start_line and end_line to page through large files
Example Usage
Read entire file:
{
"skill": "read_file",
"args": {
"path": "src/config.ts"
}
}
{
"skill": "read_file",
"args": {
"path": "logs/server.log",
"start_line": 1000,
"end_line": 1100
}
}
Response Examples
Small file:
export const config = {
apiKey: process.env.API_KEY,
baseUrl: 'https://api.example.com',
timeout: 30000
};
[/home/user/.orcbot/workspace/data/large.json (lines 1–50 of 5000)]
{"records": [
{"id": 1, "name": "Alice", ...},
{"id": 2, "name": "Bob", ...},
...
]}
[...truncated. 85000 chars total. Use start_line/end_line to read specific sections.]
Error Handling
File not found:
Error: File not found: /home/user/.orcbot/workspace/src/missing.ts. However, the parent directory exists and contains these files: index.ts, config.ts, utils.ts. Check for typos.
Error: Path exists but is a directory, not a file: /home/user/.orcbot/workspace/src. Use the 'list_directory' skill to see its contents.
- isDeep:
true - Counts as substantive progress
- isParallelSafe:
true - Safe to run in parallel workers
For large files, read in chunks. Use start_line and end_line to avoid truncation. Each chunk can be up to 20,000 chars.
write_file
Write or append content to a file.
Parameters
File path (absolute or relative to workspace)
Append to existing file instead of overwriting
Return Value
Confirmation message with absolute file path
Limits
- Max content size: 10 MB per write operation
- Auto-creates parent directories: No need to create directories first
Example Usage
Create new file:
{
"skill": "write_file",
"args": {
"path": "output/results.json",
"content": "{\"status\": \"success\", \"count\": 42}"
}
}
{
"skill": "write_file",
"args": {
"path": "logs/activity.log",
"content": "[2025-01-15 10:30:00] Task completed successfully\n",
"append": true
}
}
Response Examples
Success:
File created: /home/user/.orcbot/workspace/output/results.json
Content appended to /home/user/.orcbot/workspace/logs/activity.log
Error Handling
Content too large:
Error: Content too large (> 10 MB). Split the write into smaller chunks.
Error: Access to restricted path "/home/user/.orcbot/workspace/node_modules/package.json" is blocked. Agent skills are not permitted to access node_modules or .git directories.
- isDeep:
true
- isParallelSafe:
false (concurrent writes to same file are unsafe)
Use write_file instead of shell commands. Always prefer this skill over echo > or cat <<EOF for creating files. It’s cross-platform, handles escaping correctly, and enforces size limits.
list_directory
List files and subdirectories in a directory.
Parameters
Directory path. Defaults to workspace root if omitted.
Return Value
Formatted list with emoji indicators:
- 📁 for directories
- 📄 for files
Example Usage
List workspace root:
{
"skill": "list_directory",
"args": {}
}
{
"skill": "list_directory",
"args": {
"path": "src/components"
}
}
Response Example
Contents of /home/user/.orcbot/workspace/src:
📁 components
📁 utils
📁 services
📄 index.ts
📄 config.ts
📄 types.ts
Error Handling
Directory not found:
Error: Directory not found: /home/user/.orcbot/workspace/src/missing. However, the parent directory exists and contains: components, utils, index.ts. Check for typos or if the folder should have been created first.
Error: Path exists but is a file, not a directory: /home/user/.orcbot/workspace/src/index.ts. Use the 'read_file' skill to view its contents.
- isDeep:
true
- isParallelSafe:
true
Use list_directory to explore structure. Start with the workspace root to understand the project layout, then navigate deeper.
create_directory
Create a directory and all parent directories.
Parameters
Return Value
Confirmation message or “already exists” if directory exists
Example Usage
{
"skill": "create_directory",
"args": {
"path": "output/reports/2025"
}
}
Response Examples
Success:
Directory created: /home/user/.orcbot/workspace/output/reports/2025
Directory already exists: /home/user/.orcbot/workspace/output/reports/2025
- isDeep:
true
- isParallelSafe:
false (concurrent directory creation can race)
create_directory uses recursive: true, so it creates all missing parent directories automatically. No need to create intermediate paths.
Parameters
Absolute path to the file
Question or instruction. Defaults to “Describe the content of this file.”
Return Value
AI-generated description or analysis
- Images: JPEG, PNG, GIF, WebP, SVG
- Audio: MP3, WAV, OGG (transcription)
- Documents: PDF (OCR + text extraction)
Example Usage
Analyze image:
{
"skill": "analyze_media",
"args": {
"path": "/home/user/.orcbot/downloads/screenshot.png",
"prompt": "What error message is shown in this screenshot?"
}
}
{
"skill": "analyze_media",
"args": {
"path": "/home/user/.orcbot/downloads/voicemail.mp3"
}
}
Response Example
The screenshot shows a terminal window with a red error message reading "Error: Connection refused on port 5432". The error appears to be from a PostgreSQL database connection attempt.
Use analyze_media after downloading files with download_file to extract insights without manual inspection.
Common Workflows
Download and Process
download_file - Download from webanalyze_media or read_file - Extract contentwrite_file - Save processed results
Generate and Deliver
generate_image or text_to_speech - Create mediasend_file - Deliver to user
Read, Modify, Write
read_file - Load existing file- Process content (using LLM or code execution)
write_file - Save updated version
Best Practices
File operation strategy:
- Use
list_directory to explore structure before reading
- Read large files in chunks with
start_line/end_line
- Always use
write_file instead of shell redirection
- Use
analyze_media for images and audio instead of guessing content
Avoid these mistakes:
- Don’t use
run_command with echo > — use write_file
- Don’t guess file paths — use
list_directory first
- Don’t read entire huge files — use line ranges
- Don’t write >10MB in one call — chunk it
