ao open

Open session(s) in terminal tabs

The ao open command opens one or more agent sessions in terminal tabs, providing quick access to running agents.

Syntax

ao open [target] [options]

Arguments

target · string

Session name, project ID, or “all” to open everything. If omitted, opens all sessions.

Options

-w, --new-window · flag

Open sessions in a new terminal window instead of tabs

Behavior

The command accepts three types of targets:

1. Specific session - Opens a single session by name (e.g., ao open my-app-1)
2. Project ID - Opens all sessions for a project (e.g., ao open frontend)
3. “all” or omitted - Opens all sessions across all projects

Terminal Integration

On macOS, the command uses the iTerm2 terminal plugin via the open-iterm-tab script to open sessions in tabs or windows. If iTerm2 integration is not available, it displays tmux attach commands as a fallback.

Examples

Open a specific session

ao open my-app-1

Opens the session my-app-1 in a new terminal tab.

Open all sessions for a project

ao open frontend

Opens all sessions with the frontend project prefix (e.g., fe-1, fe-2, fe-3).

Open all sessions

ao open all
# Or simply:
ao open

Opens every active session across all configured projects.

Open in a new window

ao open my-app-1 --new-window

Opens the session in a new terminal window instead of a tab.

Output

The command displays the status of each session as it opens:

Opening 3 sessions...

  Opened: frontend-1
  Opened: frontend-2
  Opened: frontend-3

If iTerm2 integration is unavailable, it provides tmux attach commands:

Opening 2 sessions...

  backend-1 — attach with: tmux attach -t backend-1
  backend-2 — attach with: tmux attach -t backend-2

Error Handling

Unknown target

Error: Unknown target: xyz

Cause: The specified target is not a session name, project ID, or “all”.

Solution: Run ao status to see active sessions and project IDs, then specify a valid target.

No sessions to open

Message: No sessions to open.

Cause: No sessions are running for the specified target.

Solution: Start sessions with ao spawn before trying to open them.

Prerequisites

• iTerm2 (macOS only) - For automatic tab/window opening
• tmux - All sessions run in tmux
• open-iterm-tab script - Must be in PATH for terminal integration

Related Commands

• ao status - View all active sessions
• ao session ls - List sessions with metadata
• ao spawn - Create new sessions to open