Files Channel

File system operations and real-time watching

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

Response:

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

Response:

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

Response:

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