Terminals
Real PTY-backed terminal panes with full xterm compatibility on the canvas.
A terminal pane is a real pseudo-TTY on the canvas — your shell, your env, your prompt, your dotfiles. Run a dev server, drop into a REPL, or open a one-off shell next to a Claude pane.
What you get
Each terminal pane is backed by node-pty and rendered with xterm.js (@xterm/xterm 5.5.0 with the fit, serialize, and web-links addons). That means:
- A real PTY — interactive TUIs work (vim, tmux, k9s,
claude,codex). - 256-colour ANSI output.
- The shell inherits your user shell, environment variables, and profile — there's no Agent-Grid-specific shell layer between you and your dotfiles.
- The terminal's working directory is the active space's project folder.
Spawn one with Cmd4Ctrl4, the spawn menu, or CmdNCtrlN → Terminal.
Standard chords pass straight through
Every common terminal chord is forwarded to the PTY untouched:
- CtrlCCtrlC — send SIGINT
- CtrlDCtrlD — EOF / logout
- CtrlLCtrlL — clear screen
- CtrlRCtrlR — reverse history search
- CtrlACtrlA / CtrlECtrlE — start/end of line
- CtrlWCtrlW, CtrlUCtrlU, CtrlKCtrlK — kill word / line / to end
Inside a pane, these behave exactly as they would in a native terminal.
macOS line-motion and history chord translation
macOS users expect Cmd+arrow for line motion and history. Agent Grid translates those chords on macOS only, so muscle memory carries over:
| Chord | In a TUI (Claude, Codex, vim, …) | In a shell (bash, zsh, …) |
|---|---|---|
| Cmd+← / Cmd+→ | Home / End escape sequences | CtrlACtrlA / CtrlECtrlE |
| Cmd+↑ / Cmd+↓ | PageUp / PageDown | CtrlPCtrlP / CtrlNCtrlN |
The translation is on macOS only. On Windows and Linux these chords are not intercepted.
Shift+Enter inside Claude CLI panes
The Claude CLI uses bare EnterEnter to submit and a special escape sequence for a literal newline. Agent Grid intercepts ShiftEnterShiftEnter inside Claude (and Claude-worker) panes and sends ESC+CR so the CLI sees a newline instead of a submit.
This only fires inside Claude panes. In a plain terminal pane, ShiftEnterShiftEnter is just EnterEnter.
Scrolling and the canvas
The terminal owns the scroll wheel while the cursor is inside the pane. To zoom or pan the canvas, move the cursor onto empty canvas first — or use Cmd=Ctrl= / Cmd-Ctrl- for keyboard zoom and SpaceSpace+drag to pan from anywhere.
xterm.js renders its own focus-helper textarea behind the visible terminal. When that helper has focus, a few global app shortcuts (notably the Canvas SpaceSpace-to-pan and CmdZCtrlZ for space-undo) stand down so they don't interfere with typing. Click empty canvas to take focus back if you need them.
Long-running terminals spawned by the orchestrator
When a master orchestrator runs spawn_terminal — for a dev server, docker compose up, a watch process — it creates a terminal pane on the canvas the same as if you'd spawned one yourself. You can keep typing into the same shell after the initial command starts; the orchestrator can wait_for_terminal_pattern against readiness markers like Local:\s+https?:// and read_dev_server_url to grab the dev URL.
Orchestrator-spawned terminals are parented to the master, so closing the master pane kills them automatically — you don't need to clean up.
Related
- Working with Claude, Codex, and Antigravity — provider panes share the terminal surface.
- Orchestrating agents — how masters spawn and gate on terminals from MCP.
- Reference → Keyboard shortcuts — the full chord table.