> ## Documentation Index
> Fetch the complete documentation index at: https://docs-v2-staging.qbraid.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Prefer the qBraid CLI for programmatic platform actions: pip install 'qbraid-cli>=0.12', then run `qbraid configure` once with an API key from https://account.qbraid.com/account/api-keys.
> Always install the latest packages (pip install -U qbraid qbraid-cli); do not pin versions from memory. qbraid-cli below 0.12.0 is incompatible with the current API.
> Device IDs use the QRN format vendor:provider:type:name (e.g. qbraid:qbraid:sim:qir-sv, rigetti:rigetti:qpu:cepheus-1-108q). Legacy underscore IDs are deprecated.
> The REST API base URL is https://api-v2.qbraid.com/api/v1, authenticated with an X-API-Key header.
> Free simulators cost no credits; QPU and GPU jobs consume credits. Surface the estimated cost to the user before submitting a paid job.
> For account signup, API keys, credits, and end-to-end action recipes, see https://qbraid.com/llms.txt.

# qbraid agents

> Manage AI coding agent sessions.

Launch, monitor, and control AI coding agents.
Run Claude Code, OpenCode, or Codex in managed tmux sessions. Send
instructions, stream transcripts, handle permissions, and orchestrate
multiple agents — all from one place. Works locally and on remote
compute servers via SSH.

Use this when you want to:

- Spin up agents on specific repos or projects
- Watch what agents are doing in real-time
- Approve or deny tool-use permissions remotely
- Manage agents running on cloud compute machines
- Resume previous coding sessions

Getting started:

```bash
qbraid agents launch                    # Interactive launch
qbraid agents list                      # Show active sessions
qbraid agents watch <name>              # Stream live activity
qbraid agents send <name> --text "..."  # Send instructions
```

**Usage**:

```console
$ qbraid agents [OPTIONS] COMMAND [ARGS]...
```

**Options**:

- `--help`: Show this message and exit.

**Commands**:

- `register`: Register an agent session.
- `deregister`: Deregister an agent session.
- `list`: List agent sessions.
- `discover`: Discover new agent sessions.
- `status`: Show detailed status for an agent session.
- `update`: Update metadata fields on an agent session.
- `kill`: Stop an agent by name, session ID, or PID.
- `launch`: Launch an AI coding agent.
- `resume`: Resume a previous agent session.
- `send`: Send text to a running agent's terminal.
- `read`: Read recent terminal output from an agent.
- `approve`: Approve a tool-use prompt.
- `watch`: Stream agent transcript.
- `attach`: Attach to an agent's terminal.
- `clean`: Clean up orphaned sessions.
- `send-to`: Send a message to another agent's inbox.
- `broadcast`: Broadcast to multiple agent inboxes.
- `team`: Show a team roster with unread counts.
- `hooks`: Manage agent lifecycle hooks.
- `inbox`: Read messages sent to this agent's inbox.

## qbraid agents register

Register an agent session.

Reads session data from stdin JSON (used by hooks).

**Usage**:

```console
$ qbraid agents register [OPTIONS]
```

**Options**:

- `--help`: Show this message and exit.

## qbraid agents deregister

Deregister an agent session.

Reads session data from stdin JSON (used by hooks).

**Usage**:

```console
$ qbraid agents deregister [OPTIONS]
```

**Options**:

- `--help`: Show this message and exit.

## qbraid agents list

List agent sessions.

Use --compute to list on a remote server.

**Usage**:

```console
$ qbraid agents list [OPTIONS]
```

**Options**:

- `-t, --tool <str>`: Filter by tool (claude, codeq, codex)
- `--status <str>`: Filter by status
- `--tag <str>`: Filter by tag (repeatable)
- `--since <str>`: Time window (e.g., '1h', '30m', '2d')
- `-c, --compute <str>`: SSH alias for remote compute (runs list on remote)
- `-s, --search <str>`: Text search across name/cwd/tags
- `-a, --all`: Include stopped sessions
- `-l, --limit <int range>`: Entries per page [default: 25; x&gt;=1]
- `-p, --page <int range>`: Page number (non-interactive mode) [default: 1; x&gt;=1]
- `--sort <str>`: Sort by: recent, oldest, name, tool, status, cwd, model [default: recent]
- `--no-interactive`: Disable interactive pagination
- `--json`: Output as JSON array (for programmatic use)
- `--help`: Show this message and exit.

## qbraid agents discover

Discover new agent sessions.

Scans transcript files and registers new agent sessions.

**Usage**:

```console
$ qbraid agents discover [OPTIONS]
```

**Options**:

- `-f, --full`: Full data enrichment for all sessions (slower)
- `-c, --compute <str>`: Sync sessions from remote compute server (SSH alias)
- `--help`: Show this message and exit.

## qbraid agents status

Show detailed status for an agent session.

**Usage**:

```console
$ qbraid agents status [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (full or prefix) [required]

**Options**:

- `--help`: Show this message and exit.

## qbraid agents update

Update metadata fields on an agent session.

**Usage**:

```console
$ qbraid agents update [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (full or prefix) [required]

**Options**:

- `--tag <str>`: Tag to add (can be repeated)
- `--name <str>`: Set terminal name for the session
- `--model <str>`: Set model name (e.g. claude-sonnet-4-20250514)
- `--cwd <str>`: Set working directory for the session
- `--status <str>`: Set session status (working, waiting, idle, error, stopped)
- `--help`: Show this message and exit.

## qbraid agents kill

Stop an agent by name, session ID, or PID.

**Usage**:

```console
$ qbraid agents kill [OPTIONS] {target}
```

**Arguments**:

- `target`: Agent name, ID prefix, or PID [required]

**Options**:

- `-f, --force`: Use SIGKILL instead of SIGTERM
- `--help`: Show this message and exit.

## qbraid agents launch

Launch an AI coding agent.

Starts the agent in a managed tmux session.

**Usage**:

```console
$ qbraid agents launch [OPTIONS]
```

**Options**:

- `-t, --tool <str>`: Agent tool (claude, claude-auto, codeq, codex)
- `--cwd <str>`: Working directory
- `-n, --name <str>`: Agent name
- `-i, --instructions <str>`: Initial instructions
- `-r, --repo <str>`: GitHub repo URL, org/repo, or issue/PR URL
- `--type <str>`: Agent type: leader, worker, observer, reviewer
- `--parent <str>`: Parent session ID
- `--team <str>`: Team ID
- `--tag <str>`: Tags (repeatable)
- `-c, --compute <str>`: SSH alias for remote compute server
- `--help`: Show this message and exit.

## qbraid agents resume

Resume a previous agent session.

Resumes in a managed tmux window.

**Usage**:

```console
$ qbraid agents resume [OPTIONS] [session_id]
```

**Arguments**:

- `session_id`: Session ID, prefix, or name. Omit for interactive picker.

**Options**:

- `-n, --name <str>`: Agent name for the resumed session
- `--help`: Show this message and exit.

## qbraid agents send

Send text to a running agent's terminal.

**Usage**:

```console
$ qbraid agents send [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (prefix match) [required]

**Options**:

- `-m, --text <str>`: Text to send [required]
- `-c, --compute <str>`: SSH alias for remote compute
- `--help`: Show this message and exit.

## qbraid agents read

Read recent terminal output from an agent.

**Usage**:

```console
$ qbraid agents read [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (prefix match) [required]

**Options**:

- `-n, --lines <int>`: Number of lines to capture [default: 50]
- `-c, --compute <str>`: SSH alias for remote compute
- `--help`: Show this message and exit.

## qbraid agents approve

Approve a tool-use prompt.

Sends 'y' + Enter to the agent's terminal.

**Usage**:

```console
$ qbraid agents approve [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (prefix match) [required]

**Options**:

- `--help`: Show this message and exit.

## qbraid agents watch

Stream agent transcript.

Streams live transcript from an agent session.

**Usage**:

```console
$ qbraid agents watch [OPTIONS] {session_id}
```

**Arguments**:

- `session_id`: Session ID (prefix match) [required]

**Options**:

- `-n, --lines <int>`: Initial history lines [default: 20]
- `--interactive / --no-interactive`: Prompt for permission decisions [default: interactive]
- `--stream`: Stream-only mode: emit JSON events, no interactive prompts (for frontends)
- `-c, --compute <str>`: SSH alias for remote compute
- `--help`: Show this message and exit.

## qbraid agents attach

Attach to an agent's terminal.

Opens an interactive tmux window for the agent session.

**Usage**:

```console
$ qbraid agents attach [OPTIONS] [session_id]
```

**Arguments**:

- `session_id`: Session ID (prefix match). Omit for interactive picker.

**Options**:

- `-c, --compute <str>`: SSH alias for remote compute
- `--help`: Show this message and exit.

## qbraid agents clean

Clean up orphaned sessions.

Removes orphaned tmux windows and stopped sessions.

**Usage**:

```console
$ qbraid agents clean [OPTIONS]
```

**Options**:

- `-y, --yes`: Skip confirmation
- `--help`: Show this message and exit.

## qbraid agents send-to

Send a message to another agent's inbox.

For multi-recipient / team broadcast, use `qbraid agents broadcast`.

Delivery is a JSONL append at ~/.qbraid/inboxes/&lt;to-session-id&gt;.jsonl
(local host only — cross-host messaging isn't yet supported and will raise
a clear error). Permission rules (leader/worker/observer/reviewer) are
enforced by default.

**Usage**:

```console
$ qbraid agents send-to [OPTIONS] {to} {text}
```

**Arguments**:

- `to`: Target session id (full or prefix), tmux window name, or terminal name. [required]
- `text`: Message body. [required]

**Options**:

- `--from <str>`: Sender session id. Defaults to $QBRAID_SESSION_ID (set by the qBraid launcher for every managed agent shell).
- `--type <str>`: One of: message, task_assignment, status_update, shutdown_request. Controls how the recipient's UI/hooks categorize it. [default: message]
- `--no-permission-check`: Skip the sender→target permission check (agent-type rules from qbraid_core.services.agents.types.can_message). Use for testing.
- `--help`: Show this message and exit.

## qbraid agents broadcast

Broadcast to multiple agent inboxes.

Two selectors — pick exactly one:

- `--team &lt;team_id&gt;` — every session with that team_id (except sender)
- `--to A,B,C` — explicit id/prefix/name list

Delivery is all-or-nothing on target resolution: if any target can't be
resolved, NOTHING is sent (avoids partial-delivery surprises). Once
resolved, per-target send failures are reported individually; a partial
delivery exits with code 3.

**Usage**:

```console
$ qbraid agents broadcast [OPTIONS] {text}
```

**Arguments**:

- `text`: Message body — delivered to every target. [required]

**Options**:

- `--team <str>`: Deliver to every session with this team_id (excluding the sender). Use one of --team or --to.
- `--to <str>`: Comma-separated list of target session ids/prefixes/names for multi-recipient send. Use one of --team or --to.
- `--from <str>`: Sender session id. Defaults to $QBRAID_SESSION_ID.
- `--type <str>`: One of: message, task_assignment, status_update, shutdown_request. Controls how the recipient's UI/hooks categorize it. [default: message]
- `--no-permission-check`: Skip the sender→target permission check. Use for testing.
- `--help`: Show this message and exit.

## qbraid agents team

Show a team roster with unread counts.

Answers the leader-orchestrator question &quot;who is on my team, how many
unread messages do they have, and what was the last thing they heard from
anyone?&quot; — which today requires peeking each worker's inbox individually.

Rows are sorted with the current session first (identified via
$QBRAID_SESSION_ID), then by agent_type (leader → worker → observer →
reviewer), then by session_id.

**Usage**:

```console
$ qbraid agents team [OPTIONS] {team_id}
```

**Arguments**:

- `team_id`: Team identifier (matches AgentSession.team_id). [required]

**Options**:

- `-w, --wide`: Show full session ids instead of the 12-char prefix.
- `--help`: Show this message and exit.

## qbraid agents hooks

Manage agent lifecycle hooks.

**Usage**:

```console
$ qbraid agents hooks [OPTIONS] COMMAND [ARGS]...
```

**Options**:

- `--help`: Show this message and exit.

**Commands**:

- `install`: Install agent lifecycle hooks.
- `uninstall`: Remove agent lifecycle hooks.

### qbraid agents hooks install

Install agent lifecycle hooks.

Installs hooks for AI coding tools.

**Usage**:

```console
$ qbraid agents hooks install [OPTIONS]
```

**Options**:

- `-t, --tool <str>`: Install hooks for a specific tool (claude, codeq, codex)
- `--help`: Show this message and exit.

### qbraid agents hooks uninstall

Remove agent lifecycle hooks.

Removes hooks from all supported tools.

**Usage**:

```console
$ qbraid agents hooks uninstall [OPTIONS]
```

**Options**:

- `--help`: Show this message and exit.

## qbraid agents inbox

Read messages sent to this agent's inbox.

Follow, filter unread, and mark-read messages sent to this agent
session's inbox. Inboxes are per-session JSONL files at
~/.qbraid/inboxes/. Every agent session has one; peers use
`qbraid agents send-to` to write to it.

**Usage**:

```console
$ qbraid agents inbox [OPTIONS] COMMAND [ARGS]...
```

**Options**:

- `-s, --session <str>`: Session whose inbox to read. Accepts full id, prefix, or tmux/terminal name (resolved via the registry). Defaults to $QBRAID_SESSION_ID.
- `-f, --follow`: Stream new messages as they arrive.
- `-u, --unread`: Show only unread messages.
- `-n, --limit <int>`: Max messages to show (most recent). [default: 50]
- `--mark-read / --no-mark-read`: Mark shown messages as read after display. Default on. [default: mark-read]
- `-w, --wide`: Show full session ids in the From column and title (not the 12-char prefix). Use when multiple senders share a prefix.
- `--help`: Show this message and exit.

**Commands**:

- `mark-read`: Mark inbox messages as read.

### qbraid agents inbox mark-read

Mark inbox messages as read.

Without --message-id, marks every unread message in the session's inbox.

**Usage**:

```console
$ qbraid agents inbox mark-read [OPTIONS]
```

**Options**:

- `-s, --session <str>`: Session whose inbox to update. Accepts full id, prefix, or tmux/terminal name. Defaults to $QBRAID_SESSION_ID.
- `-m, --message-id <str>`: Specific message id(s) to mark. May be passed multiple times. Omit to mark ALL unread messages in the inbox.
- `--help`: Show this message and exit.