Terminal WebSocket methods reference

The terminal methods manage pseudo-terminal (PTY) sessions on the server. Each session is identified by a threadId and a terminalId. When you open a terminal it is associated with a thread, so the thread’s working directory and environment provide the execution context. All methods are in the terminal.* namespace. Terminal output arrives through the terminal.event push channel on the WebSocket connection — you do not need an explicit subscription call to receive output events.

terminal.open

Open a new terminal session. If a session already exists for the given threadId/terminalId pair, it is returned as-is. Returns a snapshot of the session state including any buffered history.

Parameters

threadId

string

required

ID of the thread this terminal belongs to.

terminalId

string

default:"\"default\""

Identifier for the terminal session within the thread. Max 128 characters. Defaults to "default".

cwd

string

required

Working directory in which to start the shell.

cols

number

Terminal width in columns. Integer between 20 and 400.

rows

number

Terminal height in rows. Integer between 5 and 200.

env

object

Additional environment variables to set for the shell process. Keys must match [A-Za-z_][A-Za-z0-9_]*. Values max 8,192 characters. Max 128 entries.

Response (`TerminalSessionSnapshot`)

threadId

string

required

terminalId

string

required

cwd

string

required

Working directory the terminal was opened in.

status

"starting" | "running" | "exited" | "error"

required

pid

number | null

required

OS process ID of the shell, once started.

history

string

required

Buffered terminal output since the session started or was last cleared.

exitCode

number | null

required

Exit code if the session has exited.

exitSignal

number | null

required

Exit signal number if the process was killed by a signal.

updatedAt

string

required

ISO 8601 timestamp of the last status update.

terminal.write

Write data to a running terminal session. Use this to send keystrokes, commands, or control sequences.

Parameters

threadId

string

required

terminalId

string

default:"\"default\""

data

string

required

Data to write. Must be non-empty. Max 65,536 characters. To send a command followed by Enter, include "\r" or "\n" at the end.

Response

Returns void on success.

terminal.resize

Resize a terminal session to new dimensions. Send this whenever the terminal UI is resized so that line-wrapping and cursor positioning remain accurate.

Parameters

threadId

string

required

terminalId

string

default:"\"default\""

cols

number

required

New width in columns. Integer between 20 and 400.

rows

number

required

New height in rows. Integer between 5 and 200.

Response

Returns void on success.

terminal.clear

Clear the terminal history buffer. A cleared event is emitted on the terminal.event channel after this call.

Parameters

threadId

string

required

terminalId

string

default:"\"default\""

Response

Returns void on success.

terminal.restart

Restart an existing terminal session with a fresh shell process. Returns a new session snapshot. The previous process is killed.

Parameters

threadId

string

required

terminalId

string

default:"\"default\""

cwd

string

required

Working directory for the new shell process.

cols

number

required

Terminal width in columns. Integer between 20 and 400.

rows

number

required

Terminal height in rows. Integer between 5 and 200.

env

object

Additional environment variables for the new shell process.

Response

Same TerminalSessionSnapshot structure as terminal.open.

terminal.close

Close a terminal session and optionally delete its history.

Parameters

threadId

string

required

terminalId

string

Specific terminal to close. If omitted, all terminals for the thread are closed.

deleteHistory

boolean

If true, the history buffer is deleted from the server.

Response

Returns void on success.

terminal.subscribeEvents

Streaming. Subscribe to all terminal events across all sessions. Once subscribed, the server streams TerminalEvent items for every session change that occurs on this connection.

You can also receive terminal events without this subscription by listening to the terminal.event push channel. Use terminal.subscribeEvents only if you need a structured stream that replays in-order through the RPC layer.

Parameters

No parameters required.

Stream items (`TerminalEvent`)

Every event carries these base fields:

threadId

string

required

terminalId

string

required

createdAt

string

required

ISO 8601 timestamp.

type

string

required

Event type (see below).

Event types:

`type`	Additional fields
`started`	`snapshot: TerminalSessionSnapshot` — full session state
`output`	`data: string` — raw terminal output bytes
`exited`	`exitCode: number \| null`, `exitSignal: number \| null`
`error`	`message: string`
`cleared`	(no additional fields)
`restarted`	`snapshot: TerminalSessionSnapshot` — new session state
`activity`	`hasRunningSubprocess: boolean`, `cliKind: "codex" \| "claude" \| null`, `agentState: "running" \| "attention" \| "review" \| null`

Complete example: open and use a terminal

1. Open terminal
Open response
2. Write a command
Output push event
3. Resize

{
  "id": "req-term-1",
  "body": {
    "_tag": "terminal.open",
    "threadId": "thread-abc",
    "terminalId": "default",
    "cwd": "/home/user/my-project",
    "cols": 220,
    "rows": 50
  }
}

{
  "id": "req-term-1",
  "result": {
    "threadId": "thread-abc",
    "terminalId": "default",
    "cwd": "/home/user/my-project",
    "status": "running",
    "pid": 12345,
    "history": "",
    "exitCode": null,
    "exitSignal": null,
    "updatedAt": "2025-05-01T12:00:00.000Z"
  }
}

{
  "id": "req-term-2",
  "body": {
    "_tag": "terminal.write",
    "threadId": "thread-abc",
    "terminalId": "default",
    "data": "npm test\r"
  }
}

{
  "type": "push",
  "sequence": 5,
  "channel": "terminal.event",
  "data": {
    "threadId": "thread-abc",
    "terminalId": "default",
    "createdAt": "2025-05-01T12:00:01.000Z",
    "type": "output",
    "data": "> my-project@1.0.0 test\r\n"
  }
}

{
  "id": "req-term-3",
  "body": {
    "_tag": "terminal.resize",
    "threadId": "thread-abc",
    "terminalId": "default",
    "cols": 180,
    "rows": 40
  }
}

WebSocket API

Providers

Self-Hosting

Terminal WebSocket methods reference

terminal.open

Parameters

Response (`TerminalSessionSnapshot`)

terminal.write

Parameters

Response

terminal.resize

Parameters

Response

terminal.clear

Parameters

Response

terminal.restart

Parameters

Response

terminal.close

Parameters

Response

terminal.subscribeEvents

Parameters

Stream items (`TerminalEvent`)

Complete example: open and use a terminal

Build docs developers (and LLMs) love

WebSocket API

Providers

Self-Hosting

Documentation Index

​terminal.open

​Parameters

​Response (TerminalSessionSnapshot)

​terminal.write

​Parameters

​Response

​terminal.resize

​Parameters

​Response

​terminal.clear

​Parameters

​Response

​terminal.restart

​Parameters

​Response

​terminal.close

​Parameters

​Response

​terminal.subscribeEvents

​Parameters

​Stream items (TerminalEvent)

​Complete example: open and use a terminal

Build docs developers (and LLMs) love

terminal.open

Parameters

Response (`TerminalSessionSnapshot`)

terminal.write

Parameters

Response

terminal.resize

Parameters

Response

terminal.clear

Parameters

Response

terminal.restart

Parameters

Response

terminal.close

Parameters

Response

terminal.subscribeEvents

Parameters

Stream items (`TerminalEvent`)

Complete example: open and use a terminal