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

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

Prerequisites

1. macOS: Required for AppleScript support
2. iTerm2: Download from https://iterm2.com
3. tmux: Used by the default runtime plugin
   brew install tmux
   

Configuration

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

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.

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

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:

// 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:
   printf '\033]0;session-name\007' && tmux attach -t 'session-name'
   

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

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

// 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"

Never bypass the plugin’s escaping functions. Always use escapeAppleScript() and internal shellEscape() for user-provided strings.

Usage Examples

Open Single Session

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

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

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:

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

Tab detection is not case-sensitive and matches exact session names. Partial matches are not supported.

Query-Only Session Check

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

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:

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

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

Troubleshooting

Nothing happens when running ao open

Check iTerm2 is installed:

which osascript  # Should show /usr/bin/osascript
open -a iTerm     # Should open iTerm2

Check plugin is configured:

plugins:
  terminal:
    name: iterm2

Check logs:

ao logs
# Look for: [terminal-iterm2] warnings

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:

osascript -e 'tell application "iTerm2" to activate'

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.

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

tmux attach fails

error connecting to /tmp/tmux-501/default (No such file or directory)

Solutions:

1. Verify tmux session exists:

tmux ls

2. Check runtime plugin created session:

ao list  # Should show RUNNING status

3. Recreate session:

ao destroy <session-id>
ao create <project-id>

Plugin warns 'not supported on darwin'

Your OS is not macOS. The iTerm2 plugin only works on macOS.

Solution: Use a different terminal plugin:

plugins:
  terminal:
    name: web  # Use web-based terminal instead

Integration with tmux Runtime

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

Runtime creates session:

tmux new-session -d -s ao-session-abc-123

Terminal attaches to session:

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

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

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

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.

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 - Browser-based terminal alternative
• tmux Runtime - Default runtime plugin
• Terminal Plugin Interface - Technical interface
• iTerm2 Documentation - Official iTerm2 docs