Claude Code iTerm2 Tab Status

See what every Claude Code session is doing. Each iTerm2 tab shows a status prefix. ⚡ running, 💤 idle, or 🔴 needs attention (with flashing).

Installation
Claude Code (via Plugin Marketplace)
In Claude Code, register the marketplace first:
/plugin marketplace add JasperSui/jaspersui-marketplace
Then install the plugin from this marketplace:
/plugin install iterm2-tab-status@jaspersui-marketplace
On first session start, the plugin automatically:
- Creates an iTerm2 Python runtime (if not already installed)
- Deploys the adapter script to iTerm2 AutoLaunch
After the first session, restart iTerm2 (or toggle Scripts → AutoLaunch → claude_tab_status.py twice).

Manual Setup
If auto-bootstrap didn't work, run:
/iterm2-tab-status:setup
Uninstall
Run in Claude Code:
/iterm2-tab-status:uninstall
Then remove the plugin:
claude plugin uninstall iterm2-tab-status
Three states
| State | Prefix | Tab Color | Badge | Dismiss on Focus |
|---|
| Running — Claude is processing | ⚡ | No change | No | No |
| Idle — Claude finished | 💤 | No change | No | No |
| Attention — needs permission | 🔴 | Flashes orange | Yes | Yes |
Lifecycle: User submits → ⚡ → Claude finishes → 💤 → User submits → ⚡ → Claude needs permission → 🔴 flash! → User focuses → cleared
Your original tab color, title, and badge are saved and restored.
How it works
Claude Code hooks → JSON signal file → iTerm2 adapter → tab status
No screen scraping. Claude Code's official hooks API writes a signal file on every event. The unified hook handles both UserPromptSubmit (→ running) and Notification (→ idle/attention). The iTerm2 adapter polls for signal files and sets the matching tab's prefix, color, and badge by TTY. Only the attention state flashes and shows a badge — running and idle are informational prefixes that persist.
Configuration
The easiest way to configure is with the slash command in Claude Code:
/iterm2-tab-status:config
This opens an interactive prompt to change flash color, prefixes, badge, notifications, and more.
Config file
Settings are stored in ~/.config/claude-tab-status/config.json. Example with all keys and their defaults:
{
"signal_dir": "/tmp/claude-tab-status",
"color_r": 255,
"color_g": 140,
"color_b": 0,
"flash_interval": 0.6,
"prefix_running": "⚡ ",
"prefix_idle": "💤 ",
"prefix_attention": "🔴 ",
"badge_text": "⚠️ Needs input",
"badge_enabled": true,
"notify": false,
"sound": "",
"log_level": "WARNING"
}
The config file is hot-reloaded — changes take effect within ~1 second, no restart needed.
Priority order
Settings are resolved in this order (highest wins):
- Environment variable (e.g.
export CLAUDE_ITERM2_TAB_STATUS_COLOR_R=255)
- Config file (
~/.config/claude-tab-status/config.json)
- Built-in defaults
Environment variables are useful for CI or per-machine overrides without touching the config file.
<details>
<summary>Environment variable reference</summary>