Agent Bridge API

Provider-aware live terminal monitoring for Claude Code, Codex CLI, GitHub Copilot CLI, and OpenCode CLI tmux sessions.

Endpoints

List Sessions

GET /api/v1/agent-bridge/sessions?provider={provider_id}

provider is optional. Supported values are claude-code, codex-cli, copilot-cli, and opencode-cli.

{
  "sessions": [
    {
      "provider": "codex-cli",
      "provider_display_name": "Codex",
      "tmux_target": "repo-1234:0.0",
      "session_name": "repo-1234",
      "window_name": "main",
      "pane_id": "%1",
      "cwd": "/home/user/repo",
      "pid": "12345",
      "status": "active",
      "team_preset_id": 10,
      "team_preset_name": "Release validation",
      "team_slot_id": 20,
      "team_slot_name": "Reviewer",
      "team_slot_position": 2,
      "team_slot_role": "planner-reviewer",
      "team_slot_charter": "Review the plan and implementation against release goals.",
      "team_slot_color": "purple",
      "mail_member_id": 42,
      "mail_member_name": "Reviewer",
      "mail_repo_id": "repo-123",
      "mail_mcp_session_id": 81,
      "mail_wake_enabled": true,
      "mail_wake_state": "wakeable",
      "mail_wake_reason": null,
      "mail_wake_target": "repo-1234:0.0"
    }
  ],
  "count": 1
}

Team fields are present only for sessions launched from Agent Teams. Manual tmux sessions fall back to provider, repo, and tmux metadata with no team slot color.

The mail_* values are a redacted, per-pane projection. A member is included only when the discovered pane matches an observed Agent Mail session. mail_mcp_session_id is set only for one fresh authenticated MCP session bound to that pane's PID and process start, provider, and member. Wake states are wakeable, opted_out, stale, ambiguous, or unbound; mail_wake_reason gives the corresponding reason code when the pane cannot be woken. mail_wake_target is present only when the Agent Mail service confirms that exact pane is currently wakeable. Session listing is read-only: it does not synchronize or update observed sessions. These fields never expose capability tokens or their hashes.

Get Preview

GET /api/v1/agent-bridge/sessions/{target}/preview

Returns a captured pane preview.

Get Terminal Token

GET /api/v1/agent-bridge/token?target={target}&purpose=readonly

Returns a 30-second, single-use token bound to one exact tmux target and purpose. purpose=readonly is available for terminal viewing; purpose=attachment is used for attachment routes. purpose=interactive requires X-Deck-Operator-Token and permits terminal input only for that target. Agent session tokens do not authorize interactive terminal grants. An attachment or read-only token cannot be upgraded by changing the WebSocket query or sending a mode control frame.

Attach Terminal

WS /api/v1/agent-bridge/sessions/{target}/terminal?mode={mode}

Send the issued token as the single WebSocket subprotocol deck-terminal.{token}, not in the URL. mode must match the token's purpose (readonly or interactive) and the target must match exactly. The browser requests a new, operator-authorized token when switching to interactive mode. Origin validation is an additional browser check, not a substitute for the token; clients without an Origin header still need a valid scoped grant. Do not log WebSocket subprotocol headers.

Image Attachments

Use image attachments to upload a screenshot or mockup to the Claude Deck host, then paste a file-path prompt into a live tmux session.

All attachment endpoints require a fresh token from GET /api/v1/agent-bridge/token?target={target}&purpose=attachment in the X-Claude-Deck-Terminal-Token header. The paste endpoint also requires an operator token or a current authenticated Agent Mail MCP session bound to that exact live pane. An attachment token alone cannot send input.

POST /api/v1/agent-bridge/sessions/{target}/attachments
Content-Type: multipart/form-data
X-Claude-Deck-Terminal-Token: {token}

Multipart fields:

• file: PNG, JPEG, WebP, or GIF image
• prompt: optional prompt template containing {path}
• created_by: optional source label

{
  "id": 123,
  "target": "repo-1234:0.0",
  "provider": "codex-cli",
  "mime_type": "image/png",
  "size_bytes": 482103,
  "agent_path": "/home/user/.claude-registry/bridge-attachments/repo-1234/2026-06-29/185422-a1b2c3d4.png",
  "prompt_text": "Please inspect this image: /home/user/.claude-registry/bridge-attachments/repo-1234/2026-06-29/185422-a1b2c3d4.png"
}

POST /api/v1/agent-bridge/sessions/{target}/attachments/{attachment_id}/paste
X-Claude-Deck-Terminal-Token: {token}

{
  "submit": false,
  "require_interactive_relay": true
}

submit: true sends Enter after a short delay. Generated prompt text strips newlines so submit: false cannot submit accidentally.

When require_interactive_relay is true, the backend rejects the paste with 409 unless an active websocket relay for that target exists and is currently interactive. The web UI sets this flag so read-only mode is enforced server-side for UI paste actions.

GET /api/v1/agent-bridge/sessions/{target}/attachments
DELETE /api/v1/agent-bridge/sessions/{target}/attachments/{attachment_id}

Attachments are stored by default under ~/.claude-registry/bridge-attachments. In remote deployments, this path is on the Claude Deck host and must be readable by the tmux agent process.

Configuration:

• BRIDGE_ATTACHMENT_DIR: host storage directory
• BRIDGE_ATTACHMENT_AGENT_ROOT: optional agent-visible root to use in pasted paths
• BRIDGE_ATTACHMENT_MAX_BYTES: maximum accepted upload size
• BRIDGE_ATTACHMENT_RETENTION_DAYS: retention window for startup cleanup
• BRIDGE_ATTACHMENT_MAX_PER_SESSION_PER_DAY: per-session daily upload limit

Agentic interfaces can use the MCP shim tools:

• deck_attach_image_to_bridge_session(target, file_path, submit, prompt)
• deck_list_bridge_attachments(target)
• deck_paste_bridge_attachment(target, attachment_id, submit)

MCP tools intentionally omit require_interactive_relay; MCP callers are trusted agentic callers and may paste into a live tmux target without an attached browser relay. file_path is resolved on the MCP host and may point to any image readable by that trusted MCP process; the backend validates the image and copies it into the attachment store before generating the agent-visible prompt.

Spawn Session

POST /api/v1/agent-bridge/sessions

Claude Code example:

{
  "provider": "claude-code",
  "directory": "/home/user/repo",
  "mode": "plain",
  "prompt": "Review the current branch"
}

Codex example:

{
  "provider": "codex-cli",
  "directory": "/home/user/repo",
  "mode": "resume",
  "use_last": true,
  "model": "gpt-5.5",
  "approval_policy": "on-request"
}

Codex on Amazon Bedrock:

{
  "provider": "codex-cli",
  "directory": "/home/user/repo",
  "mode": "plain",
  "platform": "bedrock",
  "aws_region": "us-east-2",
  "aws_profile": "bedrock-prod",
  "bedrock_model": "openai.gpt-5.5"
}

When platform is bedrock for Codex, Agent Bridge launches Codex with model_provider = "amazon-bedrock" as a per-session config override. aws_region and aws_profile are optional non-secret environment hints; AWS credentials must already be available to the spawned process through the environment or AWS SDK credential chain.

Copilot example:

{
  "provider": "copilot-cli",
  "directory": "/home/user/repo",
  "mode": "resume",
  "use_last": true,
  "model": "claude-sonnet-4.6",
  "agent": "planner",
  "context_tier": "long_context",
  "reasoning_effort": "high",
  "plan": true,
  "remote": true
}

Delete Session

DELETE /api/v1/agent-bridge/sessions/{target}

Kills the tmux session or pane target.

Legacy Route

/api/v1/cc-bridge/* remains for compatibility. New clients should use /api/v1/agent-bridge/*.