> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
ao open [target] [options]
```

## Arguments

<ParamField path="target" type="string">
  Session name, project ID, or "all" to open everything. If omitted, opens all sessions.
</ParamField>

## Options

<ParamField path="-w, --new-window" type="flag">
  Open sessions in a new terminal window instead of tabs
</ParamField>

## 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

```bash theme={null}
ao open my-app-1
```

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

### Open all sessions for a project

```bash theme={null}
ao open frontend
```

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

### Open all sessions

```bash theme={null}
ao open all
# Or simply:
ao open
```

Opens every active session across all configured projects.

### Open in a new window

```bash theme={null}
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:

```bash theme={null}
Opening 3 sessions...

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

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

```bash theme={null}
Opening 2 sessions...

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

## Error Handling

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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`](/cli/status) - View all active sessions
* [`ao session ls`](/cli/session) - List sessions with metadata
* [`ao spawn`](/cli/spawn) - Create new sessions to open


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.