Skip to main content
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

Error: Unknown target: xyzCause: 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.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us