iterm2-tab-status

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:

1. Creates an iTerm2 Python runtime (if not already installed)
2. 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": "",
  "signal_max_age": 1800
}

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):

1. Environment variable (e.g. export CLAUDE_ITERM2_TAB_STATUS_COLOR_R=255)
2. Config file (~/.config/claude-tab-status/config.json)
3. 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.