Set up automatic iTerm2 tab titles for my Claude Code worktree workflow

iterm2-claude-worktree-tab-titles.md

Set up automatic iTerm2 tab titles for my Claude Code worktree workflow. Follow these steps exactly.

1. Create the script

Write the following to ~/.local/bin/tabtitle verbatim, then chmod +x it:

#!/usr/bin/env bash
# Rename this iTerm2 tab to the current worktree name (or $1 if given).
# Uses AppleScript, so it works from captured subprocesses like Claude Code tools.
set -euo pipefail

[[ -n "${ITERM_SESSION_ID:-}" ]] || exit 0
title="${1:-$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")}"
uuid="${ITERM_SESSION_ID##*:}"

osascript - "$uuid" "$title" <<'EOF'
on run argv
  set targetId to item 1 of argv
  set newName to item 2 of argv
  tell application "iTerm2"
    repeat with w in windows
      repeat with t in tabs of w
        repeat with s in sessions of t
          if id of s is targetId then
            tell s to set name to newName
            return
          end if
        end repeat
      end repeat
    end repeat
  end tell
end run
EOF

2. Update ~/.claude/settings.json

Back up the current file to ~/.claude/settings.json.bak first. Then MERGE the following into it. Do not remove or overwrite any existing keys, hooks, or env entries; append to existing arrays where they exist:

• Under "env", add: "CLAUDE_CODE_DISABLE_TERMINAL_TITLE": "1"
• Under "hooks"."Stop", add this entry:

{
  "hooks": [{
    "type": "command",
    "command": "cd \"$(jq -r .cwd)\" && ~/.local/bin/tabtitle"
  }]
}

After editing, validate the result parses with jq . ~/.claude/settings.json and show me a diff against the backup.

3. Update ~/.claude/CLAUDE.md

Append this line (create the file if it doesn't exist, keep all existing content):

After creating or moving into a git worktree, run ~/.local/bin/tabtitle once to rename the terminal tab to the worktree name.

4. Verify

• Confirm jq is installed (the hook depends on it); if not, tell me instead of installing anything.
• Run ~/.local/bin/tabtitle claude-test and ask me to confirm this tab is now named "claude-test". Note for me: macOS may show a one-time Automation permission prompt that I need to accept, and the hook only fully takes effect in new sessions.
• Then run ~/.local/bin/tabtitle with no arguments so the title resets to this repo's worktree name.

Do not modify anything else. If any step conflicts with existing config, stop and show me the conflict instead of resolving it yourself.