mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 05:02:07 +00:00
104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# Research Findings: Terminal Window Title Support
|
|
|
|
## iTerm2 (macOS)
|
|
|
|
### New Window Creation
|
|
```applescript
|
|
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:
|
|
```applescript
|
|
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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
# 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
|