clanker-agent/packages/clanker-teams/findings.md

Research Findings: Terminal Window Title Support

iTerm2 (macOS)

New Window Creation

tell application "iTerm"
    set newWindow to (create window with default profile)
    tell current session of newWindow
        -- Execute command in new window
        write text "cd /path && command"
    end tell
    return id of newWindow  -- Returns window ID
end tell

Window Title Setting

Important: iTerm2's AppleScript window object has a title property that is read-only.

To set the actual window title (OS title bar), use escape sequences:

tell current session of newWindow
    -- Set window title via escape sequence (OSC 2)
    write text "printf '\\033]2;Team: Agent\\007'"
    -- Optional: Set tab title via session name
    set name to "Agent"  -- This sets the tab title
end tell

Escape Sequences Reference

• \033]0;Title\007 - Set both icon name and window title
• \033]1;Title\007 - Set tab title only (icon name)
• \033]2;Title\007 - Set window title only

Required iTerm2 Settings

• Settings > Profiles > Terminal > "Terminal may set tab/window title" must be enabled
• May need to disable shell auto-title in .zshrc or .bashrc to prevent overwriting

WezTerm (Cross-Platform)

New Window Creation

# Spawn new OS window
wezterm cli spawn --new-window --cwd /path -- env KEY=val command

# Returns pane ID, need to lookup window ID

Window Title Setting

# Set window title by window ID
wezterm cli set-window-title --window-id 1 "Team: Agent"

# Or set tab title
wezterm cli set-tab-title "Agent"

Getting Window ID

After spawning, we need to query for the window:

wezterm cli list --format json
# Returns array with pane_id, window_id, tab_id, etc.

tmux (Skipped)

• tmux new-window creates windows within the same session
• True OS window creation requires spawning a new terminal process entirely
• Not supported per user request

Zellij (Skipped)

• zellij action new-tab creates tabs within the same session
• No native support for creating OS windows
• Not supported per user request

Universal Escape Sequences

All terminals supporting xterm escape sequences understand:

# Set window title (OSC 2)
printf '\033]2;My Window Title\007'

# Alternative syntax
printf '\e]2;My Window Title\a'

This is the most reliable cross-terminal method for setting window titles.

Summary Table

Feature	iTerm2	WezTerm	tmux	Zellij
New OS Window	✅ AppleScript	✅ CLI	❌	❌
Set Window Title	✅ Escape seq	✅ CLI	N/A	N/A
Set Tab Title	✅ AppleScript	✅ CLI	N/A	N/A
Get Window ID	✅ AppleScript	✅ CLI list	N/A	N/A

Implementation Notes

1. iTerm2: Will use AppleScript for window creation and escape sequences for title setting
2. WezTerm: Will use CLI for both window creation and title setting
3. Title Format: {teamName}: {agentName} (e.g., "my-team: security-bot")
4. Window Tracking: Need to store window IDs separately from pane IDs for lifecycle management