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

# iTerm2 Terminal

> macOS iTerm2 terminal tab management for agent sessions

The iTerm2 terminal plugin opens and manages terminal tabs in iTerm2 for attaching to agent sessions. It uses AppleScript to control iTerm2, creating new tabs and connecting them to tmux sessions.

## Overview

The iTerm2 terminal plugin provides:

* Automatic tab creation in iTerm2
* tmux session attachment
* Session name-based tab identification
* Existing tab detection and reuse
* Window creation if no window exists
* Bulk tab opening for multiple sessions
* macOS-only operation

<Info>
  macOS only: This plugin requires macOS and iTerm2. On other platforms, it logs a warning and performs no operations.
</Info>

## Prerequisites

1. **macOS**: Required for AppleScript support
2. **iTerm2**: Download from [https://iterm2.com](https://iterm2.com)
3. **tmux**: Used by the default runtime plugin
   ```bash theme={null}
   brew install tmux
   ```

## Configuration

Add the iTerm2 terminal plugin to your `agent-orchestrator.yaml`:

```yaml theme={null}
plugins:
  terminal:
    name: iterm2
    # No config options required
```

### Configuration Options

The iTerm2 plugin has no configuration options. It operates using iTerm2's default profile and settings.

<Note>
  The plugin uses your iTerm2 default profile settings. Customize your default profile in iTerm2 Preferences → Profiles to affect plugin behavior.
</Note>

## How It Works

### Opening a Session

When you run `ao open <session-id>`, the plugin:

1. **Checks for existing tab**: Searches all iTerm2 windows and tabs for a session with matching name
2. **Selects if found**: If tab exists, brings it to focus
3. **Creates new tab if needed**: Opens new tab with tmux attach command
4. **Sets tab name**: Names the tab/session for easy identification

### Session Name Resolution

The plugin uses the runtime handle ID (tmux session name) if available, otherwise falls back to the orchestrator session ID:

```typescript theme={null}
// Priority order:
1. session.runtimeHandle.id  // e.g., "ao-session-abc-123" (tmux name)
2. session.id                // e.g., "abc-123" (orchestrator ID)
```

### Tab Creation Process

1. Activates iTerm2
2. Creates window if none exists
3. Creates new tab with default profile
4. Sets session name
5. Executes tmux attach command:
   ```bash theme={null}
   printf '\033]0;session-name\007' && tmux attach -t 'session-name'
   ```

<Info>
  The `printf` command sets the terminal title before attaching, ensuring the tab name persists even if tmux is disconnected.
</Info>

## AppleScript Security

The plugin uses multiple layers of escaping to prevent injection:

1. **AppleScript escaping**: Escapes special characters for AppleScript strings
2. **Shell escaping**: Escapes single quotes for shell commands
3. **Double escaping**: Shell-escape first, then AppleScript-escape for write commands

```typescript theme={null}
// Example: Session name with special characters
const sessionName = "my-session's-name";

// AppleScript escape: "my-session's-name" → "my-session\'s-name"
// Shell escape: "my-session's-name" → "my-session'\''s-name"
```

<Warning>
  Never bypass the plugin's escaping functions. Always use `escapeAppleScript()` and internal `shellEscape()` for user-provided strings.
</Warning>

## Usage Examples

### Open Single Session

```bash theme={null}
ao open my-session-id
```

This will:

* Create/select iTerm2 tab for the session
* Attach to the tmux session
* Focus the tab

### Open All Sessions

```bash theme={null}
ao open --all
```

This will:

* Open tabs for all active sessions
* 300ms delay between each tab (avoid AppleScript race conditions)
* Reuse existing tabs where possible

### Check if Session is Open

```bash theme={null}
ao list  # Shows which sessions have terminals open
```

The plugin tracks opened sessions and reports their status.

## Advanced Features

### Existing Tab Detection

The plugin searches all iTerm2 windows and tabs for matching session names:

```applescript theme={null}
tell application "iTerm2"
    repeat with aWindow in windows
        repeat with aTab in tabs of aWindow
            repeat with aSession in sessions of aTab
                if name of aSession is equal to "session-name" then
                    select aWindow
                    select aTab
                    return "FOUND"
                end if
            end repeat
        end repeat
    end repeat
    return "NOT_FOUND"
end tell
```

<Note>
  Tab detection is **not** case-sensitive and matches exact session names. Partial matches are not supported.
</Note>

### Query-Only Session Check

The `isSessionOpen()` method checks for tab existence **without** selecting it:

```typescript theme={null}
const isOpen = await terminal.isSessionOpen(session);
// Returns true/false, does NOT change focus
```

This is useful for status checks without disrupting the user's workflow.

### Bulk Opening with Delays

When opening multiple sessions, the plugin adds 300ms delays between operations:

```typescript theme={null}
for (const session of sessions) {
  await openTab(session);
  await new Promise(resolve => setTimeout(resolve, 300));
}
```

<Info>
  The delay prevents AppleScript race conditions where rapid tab creation can cause tabs to be created in the wrong window or order.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nothing happens when running ao open">
    **Check iTerm2 is installed:**

    ```bash theme={null}
    which osascript  # Should show /usr/bin/osascript
    open -a iTerm     # Should open iTerm2
    ```

    **Check plugin is configured:**

    ```yaml theme={null}
    plugins:
      terminal:
        name: iterm2
    ```

    **Check logs:**

    ```bash theme={null}
    ao logs
    # Look for: [terminal-iterm2] warnings
    ```
  </Accordion>

  <Accordion title="Error: osascript execution failed">
    **Grant iTerm2 automation permissions:**

    1. System Preferences → Security & Privacy → Privacy
    2. Select "Automation" in left sidebar
    3. Find your terminal app (Terminal.app, iTerm2, etc.)
    4. Enable checkbox for "iTerm.app"

    **Test AppleScript manually:**

    ```bash theme={null}
    osascript -e 'tell application "iTerm2" to activate'
    ```
  </Accordion>

  <Accordion title="Tabs created in wrong window">
    This can happen with rapid tab creation. Solutions:

    1. Close extra iTerm2 windows
    2. Use `ao open` for individual sessions (not `--all`)
    3. Wait a moment between manual `ao open` commands

    The 300ms delay in `openAll()` helps, but can't prevent all race conditions.
  </Accordion>

  <Accordion title="Tab name doesn't match session">
    The plugin sets both:

    * iTerm2 session name (persists)
    * Terminal title (via printf escape sequence)

    If the name is wrong:

    1. Check session.runtimeHandle.id in metadata
    2. Verify tmux session name matches
    3. Check for shell profile overrides (PS1, etc.)
  </Accordion>

  <Accordion title="tmux attach fails">
    ```
    error connecting to /tmp/tmux-501/default (No such file or directory)
    ```

    **Solutions:**

    1. Verify tmux session exists:

    ```bash theme={null}
    tmux ls
    ```

    2. Check runtime plugin created session:

    ```bash theme={null}
    ao list  # Should show RUNNING status
    ```

    3. Recreate session:

    ```bash theme={null}
    ao destroy <session-id>
    ao create <project-id>
    ```
  </Accordion>

  <Accordion title="Plugin warns 'not supported on darwin'">
    Your OS is not macOS. The iTerm2 plugin only works on macOS.

    **Solution**: Use a different terminal plugin:

    ```yaml theme={null}
    plugins:
      terminal:
        name: web  # Use web-based terminal instead
    ```
  </Accordion>
</AccordionGroup>

## Integration with tmux Runtime

The iTerm2 plugin is designed to work with the tmux runtime plugin:

**Runtime creates session:**

```bash theme={null}
tmux new-session -d -s ao-session-abc-123
```

**Terminal attaches to session:**

```bash theme={null}
tmux attach -t ao-session-abc-123
```

**Lifecycle:**

1. Runtime creates tmux session
2. Runtime stores session ID in `runtimeHandle.id`
3. Terminal reads `runtimeHandle.id` for session name
4. Terminal runs `tmux attach` with that name

<Note>
  If using a different runtime plugin, ensure it sets `runtimeHandle.id` to a value the terminal can use for attachment.
</Note>

## macOS Catalina+ Permissions

On macOS Catalina (10.15) and later, you may need to grant additional permissions:

1. **System Events access**: Required for AppleScript
2. **Automation access**: Required to control iTerm2
3. **Accessibility access**: May be required for window focus

<Warning>
  If iTerm2 prompts for permissions during first use, **grant them immediately**. Denying permissions will break the plugin until you manually grant them in System Preferences.
</Warning>

## Comparison with Web Terminal

| Feature | iTerm2 | Web |
| - | - | - |
| Platform | macOS only | Any |
| Setup | iTerm2 required | Browser required |
| Tab management | Native OS tabs | Browser tabs |
| Keyboard shortcuts | iTerm2 shortcuts | xterm.js shortcuts |
| Copy/paste | Native | Browser-dependent |
| Customization | iTerm2 profiles | CSS/config |
| Remote access | Local only | Can be remote |
| Performance | Native | JavaScript |

## Source Code

View the plugin source:

* Package: `@composio/ao-plugin-terminal-iterm2`
* Location: `packages/plugins/terminal-iterm2/src/index.ts`
* Functions:
  * `runAppleScript()` - Execute AppleScript snippets
  * `shellEscape()` - Escape strings for shell
  * `escapeAppleScript()` - Escape strings for AppleScript (from core)
  * `findAndSelectExistingTab()` - Search and focus existing tab
  * `openNewTab()` - Create new tab with tmux attach

## Related

* [Web Terminal](/plugins/terminal/web) - Browser-based terminal alternative
* [tmux Runtime](/plugins/runtime/tmux) - Default runtime plugin
* [Terminal Plugin Interface](/api/terminal) - Technical interface
* [iTerm2 Documentation](https://iterm2.com/documentation.html) - Official iTerm2 docs


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