Claude Code 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:

Then install the plugin from this 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:

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:

Uninstall

Run in Claude Code:

Then remove the plugin:

Three states

Lifecycle: User submits → ⚡ → Claude finishes → 💤 → User submits → ⚡ → Claude needs permission or asks a question → 🔴 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

No screen scraping. Claude Code's official hooks API writes a signal file on every event. The unified hook handles UserPromptSubmit (→ running), Notification (→ idle/attention), and the…