Terminal Channel

The terminal channel runs PTY sessions inside the workspace. Multiple sessions multiplex over one connection, keyed by sessionId. See the WebSocket overview for how to connect and authenticate. A session spawns a shell resolved from $SHELL, falling back to bash. The PTY uses TERM=xterm-256color, starts at 80×24, and runs in the project working directory.

Client to Server

`create`

Open a new PTY session. Carries only the session ID — sizing is set afterward with resize. Reusing an existing sessionId is an error.

{
  "channel": "terminal",
  "type": "create",
  "sessionId": "cli-123"
}

Field	Type	Description
`sessionId`	string	Unique identifier for this session

`input`

Send keystrokes to a session.

{
  "channel": "terminal",
  "type": "input",
  "sessionId": "cli-123",
  "data": "ls -la\n"
}

Field	Type	Description
`sessionId`	string	Target session
`data`	string	Raw input (include `\n` for Enter, `\t` for Tab)

`resize`

Resize a session. Send when the terminal UI changes size. Both dimensions must be positive integers.

{
  "channel": "terminal",
  "type": "resize",
  "sessionId": "cli-123",
  "cols": 200,
  "rows": 50
}

Field	Type	Description
`sessionId`	string	Target session
`cols`	integer	New width in columns
`rows`	integer	New height in rows

`close`

Close a session and terminate its shell.

{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123"
}

Field	Type	Description
`sessionId`	string	Session to close

Server to Client

`output`

PTY output, including ANSI escape codes.

{
  "channel": "terminal",
  "type": "output",
  "sessionId": "cli-123",
  "data": "total 48\ndrwxr-xr-x  12 user  staff   384 Feb 20 10:30 .\n"
}

Field	Type	Description
`sessionId`	string	Source session
`data`	string	Raw terminal output

`close`

The session’s shell process exited. The message carries only the session ID — there is no exit code on the wire.

{
  "channel": "terminal",
  "type": "close",
  "sessionId": "cli-123"
}

Field	Type	Description
`sessionId`	string	Session that ended

​Client to Server

​create

​input

​resize

​close

​Server to Client

​output

​close

​Example Flow

Client to Server

`create`

`input`

`resize`

`close`

Server to Client

`output`

`close`

Example Flow