Core concepts
Terminal
Agents run in a real embedded terminal. Spec ADE supports three connection styles: Auggie and Claude over PTY, plus agents that speak ACP.
Two connection modes
| Mode | For | Mechanism |
|---|---|---|
| pty | Auggie · Claude Code | Terminal emulation via portable-pty, I/O over WebSocket |
| acp | Agents speaking the Agent Client Protocol | A dedicated process with sequence-numbered events for replay |
The WebSocket protocol
For PTY sessions, the frontend and backend exchange JSON messages over WebSocket:
Client → Server
| type | Payload | Description |
|---|---|---|
| input | data: string | Raw keystrokes |
| submit | data: string | Line content + Enter |
| resize | cols, rows | Terminal resize |
Server → Client
| type | Payload | Description |
|---|---|---|
| output | data: string | PTY stream data |
| ready | — | Agent ready (bracketed paste) |
| exit | code: number | Process exited |
Ready detection
Spec ADE treats an agent as “ready” when the terminal enables bracketed paste mode. Input is gated until the ready signal arrives — preventing stray keystrokes.
ACP — Agent Client Protocol
ACP agents run in a dedicated process and communicate over an event channel. Each event carries a sequence number, so on reconnect the client sends ?after_seq=N and the backend replays missed events.
Scoped permissions
Filesystem operations are path-validated; sensitive requests require user approval.
Auto-reconnect
On WS close, client retries with exponential backoff (1s → 30s cap).