> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcbot.buzzchat.site/llms.txt > Use this file to discover all available pages before exploring further. # File Operations > Read, write, and manage files with line range support and workspace sandboxing # 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 1. Absolute paths: Resolved as-is (subject to restriction checks) 2. Relative paths: Resolved relative to workspace root 3. Empty path (for `list_directory`): Defaults to workspace root **Example:** ```javascript theme={null} // 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:** ```json theme={null} { "skill": "read_file", "args": { "path": "src/config.ts" } } ``` **Read specific lines:** ```json theme={null} { "skill": "read_file", "args": { "path": "logs/server.log", "start_line": 1000, "end_line": 1100 } } ``` ### Response Examples **Small file:** ```typescript theme={null} 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 File path (absolute or relative to workspace) Content to write 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:** ```json theme={null} { "skill": "write_file", "args": { "path": "output/results.json", "content": "{\"status\": \"success\", \"count\": 42}" } } ``` **Append to existing file:** ```json theme={null} { "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 < ## 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:** ```json theme={null} { "skill": "list_directory", "args": {} } ``` **List specific directory:** ```json theme={null} { "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 Directory path to create ### Return Value Confirmation message or "already exists" if directory exists ### Example Usage ```json theme={null} { "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 Absolute path to the file Question or instruction. Defaults to "Describe the content of this file." ### Return Value 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:** ```json theme={null} { "skill": "analyze_media", "args": { "path": "/home/user/.orcbot/downloads/screenshot.png", "prompt": "What error message is shown in this screenshot?" } } ``` **Transcribe audio:** ```json theme={null} { "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 1. `download_file` - Download from web 2. `analyze_media` or `read_file` - Extract content 3. `write_file` - Save processed results ### Generate and Deliver 1. `generate_image` or `text_to_speech` - Create media 2. `send_file` - Deliver to user ### Read, Modify, Write 1. `read_file` - Load existing file 2. Process content (using LLM or code execution) 3. `write_file` - Save updated version ## Best Practices **File operation strategy:** 1. Use `list_directory` to explore structure before reading 2. Read large files in chunks with `start_line`/`end_line` 3. Always use `write_file` instead of shell redirection 4. 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 ## Related Skills Download files from the web Execute file processing scripts