iterm3

name	iterm3
description	Use when Claude is being used as "Claude Code" in iTerm2. Manipulate the current iTerm2 window in the ways the user usually does: starting with a 2-pane workspace (claude and bash), adjusting font for context (e.g. smaller fonts for a "git diff", different colours for ssh to selected servers), sending commands to a specific pane, and more.

iterm3

Overview

Manage the iTerm2 workspace the way Alan uses it: two panes, each with a role, with font and colour adapted to context.

Standard Layout

┌─────────────┬─────────────┐
│             │             │
│   claude    │    air      │
│             │             │
└─────────────┴─────────────┘

• Left: claude profile — wider, larger font, full height
• Top-right: air profile — normal font

Changed layout

Most new panes should be opened under air, e.g. if we open a new vim pane it would look like this

┌─────────────┬─────────────┐
│             │    air      │
│   claude    ├─────────────┤
│             │    vim      │
└─────────────┴─────────────┘

Any new AI panes should open under claude, e.g. if we opened a new gemini pane it might look like this:

┌─────────────┬─────────────┐
│   claude    │             │
├─────────────┤     air     │
│   gemini    │             │
└─────────────┴─────────────┘

Profiles

Run iterm_3.py profiles to get the authoritative list from iTerm2 preferences. Known useful profiles as of last check:

Profile	Default use
Claude	Claude Code session
air	bash shell
vim	Editing files
ipysyte	ipython REPL, pysyte
izatso	ipytho REPL, zatso
ipudb	pudb debugger
ranger	File manager
Gemini	Gemini session
Rovo	Rovo Dev session
ChatGPT	ChatGPT session
mac/mini	SSH to local servers
alan/jalanb	User shells
RTFM	Read Claude's manual

The following profiles should NOT be opened by Claude, as they mess with the clipboard, or otherwise annoy the user:

• AIs
• nvim
• t
• v
• z
• RTFC

FYI: the profile "air" is named for the MacBook Air; this is where user controls the machine.

Font Adjustments

Adjust font size relative to profile default — do not hardcode sizes.

Context	Adjustment
git diff / git d (side-by-side)	Shrink significantly
ssh to remote server	Shrink slightly
Normal work	Profile default
Presenting / sharing screen	Enlarge

Restore to profile default when context ends.

Colour Adjustments

Context	Adjustment
ssh ...1–...9	Distinct colour per server
Normal bash	Profile default

Python CLI

Prefer iterm_3.py over raw AppleScript — it's a thin wrapper with a clean interface:

python3 ~/.claude/skills/iterm3/iterm_3.py profiles        # list all iTerm2 profile names
python3 ~/.claude/skills/iterm3/iterm_3.py list            # list open sessions in current tab only
python3 ~/.claude/skills/iterm3/iterm_3.py send --to air "git status"
python3 ~/.claude/skills/iterm3/iterm_3.py send --focus vim "vim ~/.bashrc"
python3 ~/.claude/skills/iterm3/iterm_3.py font --delta -4
python3 ~/.claude/skills/iterm3/iterm_3.py font --reset
python3 ~/.claude/skills/iterm3/iterm_3.py new             # new tab with Claude+air+vim
python3 ~/.claude/skills/iterm3/iterm_3.py new win         # new window with Claude+air+vim
python3 ~/.claude/skills/iterm3/iterm_3.py new here        # adapt current tab

Fall back to raw AppleScript only when you need something iterm_3.py doesn't cover. list only covers the current tab — use AppleScript directly for cross-tab session searches.

AppleScript Helpers

Reusable handlers for pane manipulation:

-- Send a command to other panes without stealing focus
on sendToOtherPane(cmd)
    tell application "iTerm2"
        tell current window
            tell current tab
                set activeId to id of current session
                repeat with s in sessions
                    if id of s is not activeId then
                        tell s to write text cmd
                    end if
                end repeat
            end tell
        end tell
    end tell
end sendToOtherPane

-- Send a command to the session matching a given profile name
on sendToProfile(profileName, cmd)
    tell application "iTerm2"
        tell current window
            tell current tab
                repeat with s in sessions
                    if name of s contains profileName then
                        tell s to write text cmd
                    end if
                end repeat
            end tell
        end tell
    end tell
end sendToProfile

-- Switch to the session matching a given profile name, and send it a command
on switchToProfile(profileName, cmd)
    tell application "iTerm2"
        tell current window
            tell current tab
                repeat with s in sessions
                    if name of s contains profileName then
                        select s
                        tell s to write text cmd
                    end if
                end repeat
            end tell
        end tell
    end tell
end switchToProfile

-- Change font size in the active session
on setFontSize(ptSize)
    tell application "iTerm2"
        tell current session of current window
            set font size to ptSize
        end tell
    end tell
end setFontSize

-- Restore font size to profile default in the active session
on resetFontSize()
    tell application "iTerm2"
        tell current session of current window
            set font size to (default font size)
        end tell
    end tell
end resetFontSize

Targeting Panes

Without stealing focus (send command, stay in current pane):

sendToProfile("air", "vim /path/to/file.md")
sendToProfile("vim", ":tabnew /path/to/file.md<cr>")

With stealing focus (switch to pane, then send):

switchToProfile("vim", ":tabnew /path/to/file.md<cr>")

Font Size Examples

-- Before a wide diff
setFontSize(9)
tell application "iTerm2" to tell current session of current window to write text "git d"

-- After diff, restore
resetFontSize()

Identify panes by profile name when possible.

Sending Files to the vim Pane

The vim pane is long-running — vim is always already open there. Send vim commands, not shell commands.

• Open a file in a new tab: send :tabnew /path/to/file
• Do NOT send: vim /path/to/file — vim receives this as keystrokes, not a shell command, and /path will trigger a vim search rather than opening the file

Always send Escape first if the pane may be in a non-normal mode:

python3 ~/.claude/skills/iterm3/iterm_3.py send --to vim $'\x1b'
python3 ~/.claude/skills/iterm3/iterm_3.py send --to vim ":tabnew /path/to/file"

Edit-and-Commit Workflow

When asked to open a file for editing and commit after:

1. Send Escape then :tabnew <file> to the vim pane via iterm_3.py
2. Wait — user will signal when done (e.g. "ok" or ":wq done")
3. Read the file with the Read tool
4. Suggest a commit message
5. Commit on confirmation

Setup Layout

To create the standard 2-pane layout from scratch:

1. Open a new window with the claude profile
2. Split vertically → right pane gets air profile

Both of these profiles will default to /opt/clones/github/jalanb as their working directory

Use AppleScript or iTerm2 Python API for automation.