By strml
iTerm2 tab highlighting for Claude Code permission requests — orange tab + dock bounce on permission, auto-reset on focus
npx claudepluginhub strml/cc-iterm2-tab-alert --plugin iterm2-tab-alertA 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
Show iTerm2 tab status (running/idle/attention) for Claude Code sessions
Native Windows toast notifications for Claude Code with window activation
Warp terminal integration for Claude Code - native notifications, and more to come
Updates iTerm2 window title with Claude Code status indicators showing current activity (working, editing files, running commands, etc.)
Qiushi Skill: methodology skills for AI agents guided by seeking truth from facts, with Claude Code, Cursor, OpenClaw, Codex, OpenCode, and Hermes guidance.
Matches all tools
Hooks run on every tool call, not just specific ones
Share bugs, ideas, or general feedback.
Battle-tested Claude Code plugin for engineering teams — 50 agents, 188 skills, 68 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge.
Sign in to claim