WebSocket protocol

A single JSON protocol powers file tree, editor, terminal, git, and chat. The UI never assumes it runs on the same machine as the server.

Full spec on GitHub →

Message framing

Three message kinds, each one JSON object per text frame:

Requests (client → server)

{ "id": 1, "command": "read_file", "args": { "path": "/home/user/a.txt" } }

Replies (server → client)

{ "id": 1, "ok": true,  "result": { ... } }
{ "id": 1, "ok": false, "error": "File already exists" }

Commands run concurrently and replies may arrive out of order — match them by id. A malformed frame gets error: "invalid request: …"; an unknown command gets error: "unknown command: …".

Events (server → client)

Event	Payload	Notes
`pty-output`	`session_id`, `data`	Raw terminal bytes, ANSI escapes intact.
`pty-exit`	`session_id`, `code`	`code` is `null` when unknown.
`chat-stream-chunk`	`id`, `stream`, `text`	One line per chunk from the agent CLI.
`chat-stream-done`	`id`, `error?`	Terminates a chat stream.

Command reference

Terminal (PTY)

Command	Args	Result
`pty_spawn`	`sessionId`, `shell?`, `cwd?`, `cols?`, `rows?`	`{ id, pid }`
`pty_write`	`sessionId`, `data`	→ `null`
`pty_resize`	`sessionId`, `cols`, `rows`	→ `null`
`pty_kill`	`sessionId`	→ `null`

Shell / misc

Command	Args	Result
`run_command`	`command`	combined stdout+stderr string
`get_cwd`	—	working directory string
`chat_check_install`	`command` (agent id)	`boolean`

File system

Command	Args	Result
`read_file`	`path`	file text
`read_file_base64`	`path`	base64 string (images etc.)
`write_file`	`path`, `content`	→ `null`
`upload_file`	`path`, `content` (base64)	→ `null`
`download_file`	`path`	base64 string
`read_directory`	`path`, `maxDepth?`	`FileNode[]`
`list_files`	`path`	`string[]` recursive relative paths
`file_exists`	`path`	`boolean`
`create_file`	`path`, `content?`	→ `null`
`create_directory`	`path`	→ `null`
`rename_entry`	`from`, `to`	→ `null`
`copy_entry`	`from`, `to`	→ `null`
`delete_entry`	`path`	→ `null`
`extract_zip`	`zipContent` (base64), `destDir`	`string[]` extracted paths
`search_in_files`	`path`, `query`, `caseSensitive?`, `wholeWord?`, `regex?`	`SearchMatch[]`

Git

All git commands take path (the repo dir) plus command-specific args.

Command	Extra args	Result
`get_git_status`	—	`GitStatus`
`get_git_diff`	`file`	unified diff string
`get_git_staged_diff`	`file`	unified diff string
`get_git_head_file`	`file`	file text at HEAD
`git_show_index`	`file`	file text from the index
`git_add`	`file`	output string
`git_stage_all`	—	output string
`git_unstage`	`file`	output string
`git_unstage_all`	—	output string
`git_discard`	`file`	output string
`git_discard_all`	—	output string
`git_commit`	`message`, `amend?`	output string
`git_undo_commit`	—	output string
`git_log`	`limit?`	`GitCommitInfo[]`
`git_commit_diff`	`commit`	unified diff string
`git_stash_list`	—	`GitStashInfo[]`
`git_stash`	—	output string
`git_stash_pop`	—	output string
`git_push`	—	output string
`git_fetch`	—	output string
`git_pull`	—	output string
`git_revert`	`commit`	output string
`git_init`	—	output string
`git_branch_list`	—	`GitBranches`
`git_checkout_branch`	`name`, `create?`	output string
`git_merge`	`fromRef`	output string
`git_merge_abort`	—	output string
`git_resolve_conflict`	`file`, `side`	output string

Nio CLI chat

Command	Args	Result
`chat_stream`	`command`, `args?`, `cwd?`, `apiKey?`, `mode?`, `attachments?`, `requestId?`	fires chunk/done events; → `null`
`chat_cancel`	`id`	`{ cancelled, reason? }`
`chat_models`	`agent`, `apiKey?`	`{ id, label }[]`

chat_stream runs the Nio CLI with the selected model and context. The frontend subscribes to events before invoking so no early chunk is missed, matches chunks by requestId, and reconciles with chat-stream-done.