Files Channel - Aether

The files channel reads and writes the workspace file system and pushes change notifications as files move underneath you. Operations follow a request/response pattern keyed by requestId; watcher events are server pushes with no requestId. See the WebSocket overview for connecting. Files up to 100 MB can be read or written. Binary content is base64-encoded; text is UTF-8.

Operations

Each request carries a requestId. On success the server replies with the same type and requestId; on failure it replies with type: "error" (see Errors).

`read`

Request

{ "channel": "files", "type": "read", "requestId": "req-1", "path": "/src/index.ts" }

Response

{
  "channel": "files",
  "type": "read",
  "requestId": "req-1",
  "success": true,
  "path": "/src/index.ts",
  "content": "import express from 'express';\n...",
  "encoding": "utf8",
  "size": 1420,
  "modified": "2026-02-20T10:30:00Z",
  "isBinary": false
}

Field	Type	Description
`content`	string	File content (UTF-8 text or base64)
`encoding`	`"utf8"` \| `"base64"`	How `content` is encoded
`size`	integer	Size in bytes
`modified`	string	ISO 8601 last-modified timestamp
`isBinary`	boolean	Whether the file is binary

`write`

Writes a file, creating parent directories as needed.

{
  "channel": "files",
  "type": "write",
  "requestId": "req-2",
  "path": "/src/config.ts",
  "content": "export const PORT = 3000;\n",
  "encoding": "utf8"
}

encoding is required and must be "utf8" or "base64". The response carries success, path, size, and modified.

`list`

Lists a directory. The response field is entries (not data).

Request

{ "channel": "files", "type": "list", "requestId": "req-3", "path": "/src" }

Response

{
  "channel": "files",
  "type": "list",
  "requestId": "req-3",
  "success": true,
  "path": "/src",
  "entries": [
    { "name": "index.ts", "type": "file", "size": 1420, "modified": "2026-02-20T10:30:00Z" },
    { "name": "utils", "type": "directory", "size": 0, "modified": "2026-02-19T08:15:00Z" }
  ]
}

Each entry has name, type ("file" or "directory"), size, and modified.

`stat`

Metadata for a single path. The response is flat (no data wrapper) and uses fileType.

Request

{ "channel": "files", "type": "stat", "requestId": "req-4", "path": "/src/index.ts" }

Response

{
  "channel": "files",
  "type": "stat",
  "requestId": "req-4",
  "success": true,
  "path": "/src/index.ts",
  "fileType": "file",
  "size": 1420,
  "modified": "2026-02-20T10:30:00Z"
}

`find-paths`

Fuzzy path search across the workspace. Walks the tree, respects the repo’s ignore files, and applies the same ignore list as list.

Request

{ "channel": "files", "type": "find-paths", "requestId": "req-5", "query": "userroute", "limit": 50 }

Response

{
  "channel": "files",
  "type": "find-paths",
  "requestId": "req-5",
  "success": true,
  "entries": [
    { "path": "/src/routes/users.ts", "type": "file" }
  ]
}

Field	Type	Description
`query`	string	Fuzzy query
`limit`	integer	Optional max results, up to 200

Each match has path and type ("file" or "directory").

`mkdir`, `delete`, `rename`

mkdir

{ "channel": "files", "type": "mkdir", "requestId": "req-6", "path": "/src/components" }

delete

{ "channel": "files", "type": "delete", "requestId": "req-7", "path": "/src/old.ts" }

rename

{ "channel": "files", "type": "rename", "requestId": "req-8", "oldPath": "/src/utils.ts", "newPath": "/src/helpers.ts" }

mkdir and delete take path; rename takes oldPath and newPath. Each replies with success and the relevant path field(s).

Errors

When an operation fails, the response type is "error" (not the request type) and success is false. It carries a human-readable error, a machine-readable code, and the offending path when applicable.

{
  "channel": "files",
  "type": "error",
  "requestId": "req-1",
  "success": false,
  "error": "File not found: /src/missing.ts",
  "code": "NOT_FOUND",
  "path": "/src/missing.ts"
}

code is one of:

Code	Meaning
`NOT_FOUND`	Path does not exist
`NOT_INITIALIZED`	File operations not ready yet
`PERMISSION_DENIED`	Access denied
`IS_DIRECTORY`	Expected a file, found a directory
`IS_FILE`	Expected a directory, found a file
`FILE_TOO_LARGE`	Exceeds the 100 MB limit
`BINARY_FILE`	Operation invalid for a binary file
`INVALID_PATH`	Path is malformed or escapes the workspace
`PATH_EXISTS`	Target already exists
`INTERNAL_ERROR`	Unexpected failure

Watcher Events

The server pushes file-system changes in real time. These have no requestId.

`change`

{
  "channel": "files",
  "type": "change",
  "action": "modify",
  "path": "/src/index.ts",
  "isDirectory": false
}

Field	Type	Description
`action`	`"create"` \| `"modify"` \| `"delete"`	What happened
`path`	string	Affected path
`isDirectory`	boolean	Whether the entry is a directory

`refresh`

A signal to re-fetch the file tree, pushed after the agent or a git restore/revert rewrites files, and when the watcher overflows.

{ "channel": "files", "type": "refresh" }

Ignored Paths

The watcher and list skip these directory names: node_modules, .git, .venv, .next, .cache, dist, build, .turbo, __pycache__, .pytest_cache, coverage, .nyc_output. Listings also hide .DS_Store and lost+found.

​Operations

​read

​write

​list

​stat

​find-paths

​mkdir, delete, rename

​Errors

​Watcher Events

​change

​refresh

​Ignored Paths

Operations

`read`

`write`

`list`

`stat`

`find-paths`

`mkdir`, `delete`, `rename`

Errors

Watcher Events

`change`

`refresh`

Ignored Paths