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).
Updating
To update to the latest release:
claude plugin update iterm2-tab-status@jaspersui-marketplace
This re-fetches the plugin and installs the newest version on its own — you do not need to run /plugin marketplace update first (that only refreshes the catalog listing). After updating, restart the iTerm2 adapter (close and reopen iTerm2, or toggle Scripts → AutoLaunch → claude_tab_status.py) so it picks up any adapter-side changes.
See CHANGELOG.md for what's in each release.
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.
Prefer the prefix/badge without the color flash? Set "flash_enabled": false — the badge and notification still fire, just no tab-color flash. It's hot-reloaded, so toggling it off also stops a flash that's already in progress.
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:
{
"dir": "~/.cache/claude-tab-status",
"color_r": 255,
"color_g": 140,
"color_b": 0,
"interval": 0.6,
"flash_enabled": true,
"prefix_running": "⚡ ",
"prefix_idle": "💤 ",
"prefix_attention": "🔴 ",
"display_target": "title",
"subtitle_activity_source": "off",
"badge": "⚠️ Needs input",
"badge_enabled": true,
"notify": false,
"sound": ""
}
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.
Display target
By default, status is shown as a tab title prefix.
Set "display_target": "subtitle" to leave the main tab title alone and write status to the iTerm2 user variable user.claudeStatus. In iTerm2, open Settings > Profiles > General and set Subtitle to:
\(user.claudeStatus)
Use "display_target": "both" to update both the title prefix and subtitle variable.
