Documentation Index
Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The files channel provides file system operations and real-time file change notifications. Operations use a request-response pattern with request IDs. File watcher events are pushed from the server without a request ID.
| Constraint | Value |
|---|
| Max file size | 100 MB |
| Binary encoding | Base64 |
| Path traversal | Blocked |
Ignored Paths
The file watcher ignores changes in these directories:
node_modules, .git, .next, dist, build, __pycache__
File Operations
All operations are sent as client-to-server messages with a requestId. The server responds with a message of the same type and requestId.
list
List the contents of a directory.
{
"channel": "files",
"type": "list",
"requestId": "req-1",
"path": "/src"
}
{
"channel": "files",
"type": "list",
"requestId": "req-1",
"data": [
{ "name": "index.ts", "type": "file", "size": 1420, "modified": "2025-02-20T10:30:00Z" },
{ "name": "utils", "type": "directory", "size": 0, "modified": "2025-02-19T08:15:00Z" }
]
}
| Field | Type | Description |
|---|
name | string | File or directory name |
type | string | "file" or "directory" |
size | integer | Size in bytes (0 for directories) |
modified | string | ISO 8601 last modified timestamp |
read
Read the contents of a file. Text files return UTF-8 content. Binary files return Base64-encoded content.
{
"channel": "files",
"type": "read",
"requestId": "req-2",
"path": "/src/index.ts"
}
{
"channel": "files",
"type": "read",
"requestId": "req-2",
"data": {
"content": "import express from 'express';\n...",
"encoding": "utf-8"
}
}
| Field | Type | Description |
|---|
content | string | File content (raw text or Base64) |
encoding | string | "utf-8" for text files, "base64" for binary files |
write
Write content to a file. Creates the file if it does not exist. Creates parent directories as needed.
{
"channel": "files",
"type": "write",
"requestId": "req-3",
"path": "/src/config.ts",
"content": "export const PORT = 3000;\n",
"encoding": "utf-8"
}
| Field | Type | Required | Description |
|---|
path | string | Yes | File path to write |
content | string | Yes | File content |
encoding | string | No | "utf-8" (default) or "base64" for binary |
mkdir
Create a directory. Creates parent directories as needed.
{
"channel": "files",
"type": "mkdir",
"requestId": "req-4",
"path": "/src/components"
}
delete
Delete a file or directory.
{
"channel": "files",
"type": "delete",
"requestId": "req-5",
"path": "/src/old-file.ts"
}
rename
Rename or move a file or directory.
{
"channel": "files",
"type": "rename",
"requestId": "req-6",
"oldPath": "/src/utils.ts",
"newPath": "/src/helpers.ts"
}
| Field | Type | Required | Description |
|---|
oldPath | string | Yes | Current path |
newPath | string | Yes | New path |
stat
Get metadata for a file or directory.
{
"channel": "files",
"type": "stat",
"requestId": "req-7",
"path": "/src/index.ts"
}
{
"channel": "files",
"type": "stat",
"requestId": "req-7",
"data": {
"name": "index.ts",
"type": "file",
"size": 1420,
"modified": "2025-02-20T10:30:00Z",
"permissions": "rw-r--r--"
}
}
| Field | Type | Description |
|---|
name | string | File or directory name |
type | string | "file" or "directory" |
size | integer | Size in bytes |
modified | string | ISO 8601 last modified timestamp |
permissions | string | Unix permission string |
Watcher Events
The server pushes file change events in real time. These messages have no requestId.
change
A file or directory was created, modified, or deleted.
{
"channel": "files",
"type": "change",
"event": "modify",
"path": "/src/index.ts",
"fileType": "file"
}
| Field | Type | Description |
|---|
event | string | "create", "modify", or "delete" |
path | string | Affected file path |
fileType | string | "file" or "directory" |
Error Responses
If an operation fails, the server responds with the same requestId and an error field:
{
"channel": "files",
"type": "read",
"requestId": "req-2",
"error": "File not found: /src/missing.ts"
}
Path Security
All paths are resolved relative to the workspace root. Directory traversal attempts (e.g., ../../etc/passwd) are rejected with an error. Symlinks that resolve outside the workspace root are also blocked.
