# Terminals and agents

> Create, list, inspect, attach to, send keys or text to, read, wait on, watch, rename, move, and close terminals with v42 term, attach, ws enter, and agents.

The `term`, `attach`, `ws enter`, and `agents` commands let scripts and coding agents create and control terminals on any online Computer in your Team. Every terminal is a real persistent window on that Computer, shared live with the Vibe42 apps.

## Target syntax

Commands that act on an existing terminal take `<computer>` (ID or name) and `<target>`:

- `@N`: A window ID (such as `@12`). Commands that act on a single pane (`term send`, `term read`, `term wait`) use the window's active pane when given `@N`.
- `%N`: A pane ID (such as `%5`).
- `<session>:@N`: The qualified window target returned in `.data.target` by `v42 term new`.
- `<session>`: A tmux session name (supported by `v42 term attach` and `v42 attach` to attach to the whole session).

## Listing and inspecting terminals

```sh
v42 term list [<computer>] [--workspace <workspace>] [--idle] [--busy]
v42 term status <computer> <target>
```

- `term list`: List terminals across all Computers of the Team, or on one `<computer>`. Without a Computer, offline or unreachable Computers are reported under `computers` with their status. When you name a Computer (or a Workspace), an offline or unreachable Computer is an error (`computer_offline` and so on) instead of an empty list.
  - `--workspace <workspace>`: Only terminals belonging to this Workspace (ID or name).
  - `--idle`: Only idle terminals.
  - `--busy`: Only terminals that are not idle, including those whose state is `unknown`.
- `term status <computer> <target>`: Show one terminal window, its agent status, and its idle state; a window with several panes also lists each pane under `panes`.

### The idle rule

Each pane reports `foreground` as `idle` (the shell is at its prompt with no foreground program running), `busy` (a program is running), or `unknown` (the Computer runs Windows or an older Vibe42, or the terminal was created before Vibe42 was updated).

A terminal is **idle** only when:

1. Every pane's `foreground` is `idle`, and
2. Its [agent status](/docs/agents/agent-status), if any, is `idle` or `done` (no agent is `working`, `blocked`, or in `error`).

When a Computer cannot tell (`unknown`), the terminal counts as **busy**. `term close`, `block close`, and `tab close` never close a busy or `unknown` terminal unless you pass `--force`.

## Creating terminals

```sh
v42 term new <computer> [options]
```

Creates a terminal on `<computer>`, optionally starts an agent or command in it, and places it into the layout of its Workspace (`--workspace`) or else of the Computer.

| Option | Description |
|---|---|
| `--workspace <workspace>` | Workspace (ID or name) the terminal belongs to; its directory is the working directory (or a fresh copy when [terminal isolation](/docs/workspaces/terminal-isolation) is enabled). Cannot be combined with `--cwd`. |
| `--cwd <cwd>` | Working directory on the Computer (when `--workspace` is not used). |
| `--name <name>` | Terminal window title. |
| `--launcher <launcher>` | Agent launcher ID from `v42 agents list` to start; its display name names the terminal unless `--name` is given. `terminal` opens a plain terminal. |
| `--agent <agent>` | Agent catalog ID (`claude-code`, `codex`, `omp`, `pi`, `opencode`, `grok-build`, `devin`, `antigravity`, `cursor`, …); without `--command`, its default command runs. |
| `--command <command>` | Command started in the new terminal (single line, run inside an interactive login shell). |
| `--tab <tab>` | Open the terminal in this tab (ID, 1-based position, or title), after its last block unless `--beside` or `--float` is given. |
| `--beside <beside>` | Open the terminal next to this block (block ID, `%N` / `@N`, or 1-based position in `--tab`). |
| `--side <side>` | Side of the `--beside` block to open on: `left`, `right`, `up`, `down`, or `auto` (`auto` defaults to `right`). |
| `--float` | Open the terminal as a floating block in `--tab`, or in the first tab. |
| `--no-layout` | Do not place the terminal in any layout (an app showing the layout later gives it a tab of its own). |
| `--no-balance` | Do not rebalance the split the terminal is placed in. |
| `--attach` | Attach to the new terminal right after creating it. |
| `--stdio` | With `--attach`, relay raw bytes for a program instead of drawing a local terminal. |

### Layout effects of `term new`, `term close`, and `term move`

- **`term new`**: Without placement flags, the new terminal opens as a new tab at the top of the Workspace's (or Computer's) layout; if updating the layout fails, the terminal still exists and `.data.layout` reports `placed: false` with the error. When `--tab`, `--beside`, or `--float` is passed, the target placement is validated first so a bad target creates nothing. If an app already opened a block for the new terminal, that block is moved to the requested spot instead of duplicating it.
- **`term close`**: Waits until the Computer confirms the terminals are gone, then removes every block showing them from their Workspace or Computer layout.
- **`term move`**: Moves a window to another Workspace (or out of every Workspace with `--none`), removes its blocks from the old layout, and opens it as a new tab at the top of the destination layout unless it is already shown there.

## Attaching to a terminal

```sh
v42 term attach <computer> <target> [--stdio]
v42 attach <computer> <target> [--stdio]
v42 ws enter <workspace> [--stdio]
```

- `term attach` (and its top-level shorthand `attach`) connects your terminal to `<target>` on `<computer>`.
- `ws enter <workspace>` creates a new terminal in `<workspace>` on its Computer and attaches to it immediately.

On Windows computers, `term attach` can only attach to a whole session, not to a single window or pane.

All three are streaming commands: stdout contains only raw remote PTY bytes, and the exit code comes from the attach client. Disconnecting leaves the remote window running.

Pass `--stdio` when another program or multiplexer drives stdin/stdout:

- If stdin is not a TTY, local terminal settings are untouched and no window size is sent. When that input ends (for example piped input), `Ctrl+D` is sent to the remote terminal, which ends a shell running there; use `v42 term send` for one-off input instead.
- If stdin is a TTY, raw mode is enabled so `Ctrl+C` is sent to the remote terminal, and the local window size is pushed only after the process forwards its first input byte (and on subsequent resize events).
- When run inside a Herdr pane on macOS or Linux (`HERDR_ENV=1` and `HERDR_PANE_ID`), `attach` tags the Herdr pane with `v42_computer` and `v42_pane` and streams the pane's [agent status](/docs/agents/agent-status) to Herdr until detach (for a window or pane target; a whole-session target only gets `v42_computer` and reports no status).

## Sending input and reading the screen

```sh
v42 term send <computer> <target> [<text>] [--stdin] [--enter] [--key <key>]... [--paste] [--raw]
v42 term read <computer> <target> [--history <lines> | --all] [--raw]
```

### `term send`

Types text or presses keys in `<target>` without changing what other viewers see. When several inputs are combined, `<text>` (or `--stdin`) is typed first, then each `--key` in order, then `--enter`.

- `--stdin`: Read the text to send from standard input (up to 8 MiB).
- `--enter`: Press Enter after the text and keys.
- `--key <key>`: Repeatable. Key names: `enter`, `tab`, `backtab`, `escape`, `backspace`, `insert`, `delete`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`, `space`, `f1`–`f35`, or one character. Modifiers: `ctrl+`, `alt+`, `shift+`, `super+` (for example `ctrl+c`, `alt+x`, `shift+tab`) or tmux style `C-`, `M-`, `S-` (`C-c`, `M-x`, `S-Tab`).
- `--paste`: Wrap the text in bracketed-paste markers (`ESC[200~` … `ESC[201~`) so shells and agents treat multi-line input as a single paste.
- `--raw`: Send the bytes exactly as given, including non-UTF-8 input (`--enter` appends a carriage return; `--key` cannot be combined with `--raw`).

### `term read`

Prints the visible screen of `<target>` in `.data.lines` (or as lines with `--format text`), with trailing blank lines dropped.

- `--history <lines>`: Include up to `<lines>` of scrollback history before the visible screen.
- `--all`: Include the entire scrollback history before the visible screen.
- `--raw`: Keep ANSI escape sequences (history lines keep their colors, and the visible screen is the raw VT stream split at line feeds).

## Waiting for states and watching events

```sh
v42 term wait --until <state> [--match <pattern>] [--timeout <seconds>] <computer> <target>
v42 term watch [<computer>] [--workspace <workspace>] [--timeout <seconds>] [--count <count>]
```

### `term wait`

Blocks until `<target>` reaches `--until <state>`, then returns the terminal state as JSON. If `--timeout <seconds>` (default `600`; `0` waits without limit) elapses first, `term wait` fails with error code `wait_timeout` and exit code `8`.

| `--until` value | When it returns |
|---|---|
| `idle` | The shell is back at its prompt and no agent is `working`, `blocked`, or in `error`: after a busy period, or once the screen has stayed unchanged for 1.5 s. Needs an up-to-date Vibe42 on the Computer; not available on Windows computers (`idle_windows_unsupported`). |
| `done` | The agent finished its turn: immediately after a state transition seen during the wait, or once it has stayed `done` for 1.5 s. |
| `blocked` | The agent is waiting for the user (permission, question, or sign-in). Returns immediately if already true. |
| `error` | The agent reported an error. Returns immediately if already true. |
| `working` | The agent is working. Returns immediately if already true. |
| `gone` | The window (or the pane, when a pane target was given) closed; returns immediately with `already_gone` if it does not exist when the wait starts. |
| `output` | The visible screen changed; with `--match <pattern>`, waits until a new screen line matches the regular expression `<pattern>`. |

### `term watch`

Streams terminal changes as newline-delimited JSON (NDJSON) on stdout:

1. One `ready` line per watched Computer (or `unavailable` if a Computer cannot be watched)
2. Change events: `terminal_added`, `terminal_removed`, `renamed`, `workspace_changed`, `agent_status`, and `foreground`
3. A final `stopped` line when `--count <count>` change events have been emitted or `--timeout <seconds>` has elapsed

Omit `<computer>` to watch all online Computers in the Team, or pass `--workspace <workspace>` to filter events to one Workspace.

## Renaming, moving, and closing terminals

```sh
v42 term rename <computer> <target> [<name> | --reset]
v42 term move <computer> <window> <--workspace <workspace> | --none>
v42 term close <computer> [<targets>...] [--force] [--idle [--workspace <workspace>] [--dry-run]] [--no-balance]
```

- `term rename`: Set a custom title (up to 64 characters, trimmed) on a window `@N` or pane `%N`, or pass `--reset` to restore its automatic title.
- `term move`: Move a window `@N` to `--workspace <workspace>` on the same Computer, or out of every Workspace with `--none`, and update both layouts.
- `term close`: Close one or more windows or panes (`<targets>...`) or close every idle terminal on `<computer>` (`--idle`).
  - If any named target is not idle (or its state is `unknown`), **nothing is closed** and the command fails with `terminal_busy` (exit `2`) unless `--force` is given.
  - With `--idle`, only idle terminals owned by Vibe42 on `<computer>` (optionally filtered by `--workspace`) are closed; busy terminals and windows mirrored from Herdr or external tmux sessions (`external_source`) are left untouched and listed under `.data.skipped`. Pass `--dry-run` with `--idle` to list what would be closed without closing anything.
  - Pass `--no-balance` to leave remaining split ratios unchanged after removing the closed terminals' blocks.

## Managing agent launchers (`v42 agents`)

The agent launchers shown in the apps' new-terminal flow and used by `v42 term new --launcher <id>` are synced across your account and can be managed from the CLI:

```sh
v42 agents list
v42 agents add --command <command> [--name <name>] [--agent <agent>]
v42 agents edit <id> [--name <name>] [--command <command>]
v42 agents rm <id>
v42 agents move --index <index> <id>
v42 agents reset
```

- `agents list`: List your configured launchers (or the default list while uncustomized) alongside the built-in agent catalog.
- `agents add --command <command>`: Add a custom launcher at the end of the list (assigned ID `custom-<n>`). `<command>` is one line of at most 1024 bytes, not starting with `-`. `--name <name>` sets the display name (up to 64 characters); `--agent <agent>` binds it to a catalog ID for status detection.
- `agents edit <id>`: Update a launcher's `--name` (pass `--name ""` to restore the default name) or `--command`.
- `agents rm <id>`: Remove a launcher from your list.
- `agents move --index <index> <id>`: Move a launcher to a 1-based position.
- `agents reset`: Restore the default agent launchers, dropping all customizations.
