iTerm2 tab highlighting for Claude Code permission requests
npx claudepluginhub strml/cc-iterm2-tab-alertiTerm2 tab highlighting for Claude Code permission requests — orange tab + dock bounce on permission, auto-reset on focus
Share bugs, ideas, or general feedback.
A Claude Code plugin that highlights your iTerm2 tab when Claude needs permission. The tab turns orange and bounces the dock icon. The color resets instantly when you focus the tab.
Three components:
Notification hook — When Claude requests permission, sets the tab to orange and tags the session with an iTerm2 user variable.
Reset hook — Clears the tab color when Claude resumes work (PostToolUse) or you submit a prompt (UserPromptSubmit). Fallback for the focus-based reset.
Focus-based reset (optional) — An iTerm2 Python API script that monitors tab focus events. When you switch to a tab with an active alert, it resets the color immediately via the profile API.
/plugin marketplace add STRML/cc-iterm2-tab-alert
/plugin install iterm2-tab-alert
Then restart Claude Code. The hooks activate automatically.
For instant focus-based reset, run /iterm2-tab-alert:setup in Claude Code.
Paste this into Claude Code:
Install the iTerm2 tab alert plugin:
1. Run: /plugin marketplace add STRML/cc-iterm2-tab-alert
2. Run: /plugin install iterm2-tab-alert
3. Restart Claude Code
4. Run: /iterm2-tab-alert:setup
Copy hooks/iterm2-permission-alert.sh and hooks/iterm2-tab-reset.sh to ~/.claude/hooks/
Add the hooks from hooks/hooks.json to your ~/.claude/settings.json (replace ${CLAUDE_PLUGIN_ROOT} with $HOME/.claude/hooks in the command paths)
(Optional) Copy scripts/claude_tab_reset.py to ~/Library/Application Support/iTerm2/Scripts/AutoLaunch/
In iTerm2: Scripts > Manage > Install Python Runtime, then Scripts > claude_tab_reset
The Python script is optional. Without it, the tab color still resets — just not until Claude resumes work or you submit your next prompt.
Edit hooks/iterm2-permission-alert.sh. The format is iTerm2's proprietary OSC escape:
# RGB components (0-255) — default is orange (255, 120, 0)
printf '\033]6;1;bg;red;brightness;R\a\033]6;1;bg;green;brightness;G\a\033]6;1;bg;blue;brightness;B\a'
Remove the RequestAttention line in the alert script to disable dock icon bouncing.
Each Claude session writes its own sentinel file keyed by the TTY minor device number (stat -f '%Lr' /dev/tty), so multiple concurrent sessions don't interfere with each other.
| Escape | Purpose |
|---|---|
\033]6;1;bg;red;brightness;N\a | Set tab color red component |
\033]6;1;bg;green;brightness;N\a | Set tab color green component |
\033]6;1;bg;blue;brightness;N\a | Set tab color blue component |
\033]6;1;bg;*;default\a | Reset tab color to default |
\033]1337;RequestAttention=1\a | Bounce dock icon / flash tab |
\033]1337;SetUserVar=NAME=BASE64\a | Set session user variable |
set_use_tab_color(False) instead of async_injectiTerm2's async_inject doesn't process proprietary OSC sequences (like tab color). The focus-monitor uses the profile API (set_use_tab_color(False)) which directly controls the tab color state.
MIT