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

string

required

File path (absolute or relative to workspace)

number

1-based starting line number (inclusive)

number

1-based ending line number (inclusive)

Return Value

string

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"
  }
}

Read specific lines:

{
  "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
};

Large file (truncated):

[/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.

Path is directory:

Error: Path exists but is a directory, not a file: /home/user/.orcbot/workspace/src. Use the 'list_directory' skill to see its contents.

Metadata

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

string

required

File path (absolute or relative to workspace)

string

required

Content to write

boolean

default:"false"

Append to existing file instead of overwriting

Return Value

string

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}"
  }
}

Append to existing file:

{
  "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

Append:

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.

Restricted path:

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.

Metadata

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

string

Directory path. Defaults to workspace root if omitted.

Return Value

string

Formatted list with emoji indicators:

📁 for directories
📄 for files

Example Usage

List workspace root:

{
  "skill": "list_directory",
  "args": {}
}

List specific directory:

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

Path is file:

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.

Metadata

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

string

required

Directory path to create

Return Value

string

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

Already exists:

Directory already exists: /home/user/.orcbot/workspace/output/reports/2025

Metadata

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.

analyze_media

Use AI to analyze an image, audio, or document file.

Parameters

string

required

Absolute path to the file

string

Question or instruction. Defaults to “Describe the content of this file.”

Return Value

string

AI-generated description or analysis

Supported Formats

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?"
  }
}

Transcribe audio:

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

Metadata

isDeep: false

Use analyze_media after downloading files with download_file to extract insights without manual inspection.

Common Workflows

Download and Process

download_file - Download from web
analyze_media or read_file - Extract content
write_file - Save processed results

Generate and Deliver

generate_image or text_to_speech - Create media
send_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

Web Search

Download files from the web

Shell Execution

Execute file processing scripts

File Operations

Workspace Sandboxing

Path Resolution Rules

read_file

Parameters

Return Value

Limits

Example Usage

Response Examples

Error Handling

Metadata

write_file

Parameters

Return Value

Limits

Example Usage

Response Examples

Error Handling

Metadata

list_directory

Parameters

Return Value

Example Usage

Response Example

Error Handling

Metadata

create_directory

Parameters

Return Value

Example Usage

Response Examples

Metadata

analyze_media

Parameters

Return Value

Supported Formats

Example Usage

Response Example

Metadata

Common Workflows

Download and Process

Generate and Deliver

Read, Modify, Write

Best Practices

Related Skills

Web Search

Shell Execution