claude-iterm2
iTerm2 visual status indicators and grid layouts for Claude Code.
Features
- Tab Colors — Blue (working), yellow (waiting), green (done), red (error)
- Badge Text — Status shown in tab corner with elapsed time
- Gradient Animation — Waiting state animates from yellow to orange over time
- Done Flash — Completion briefly flashes green before settling on Done
- Error Pulse — Tool failures pulse red briefly before settling on Error
- Desktop Notifications — Get notified when tasks complete (clicks focus the right pane)
- Sound Notifications — Configurable per-state sounds
- Grid Layouts — Create organized multi-pane layouts in new tabs
- Fork Session — Fork the current conversation into a new iTerm2 pane or tab
- Auto-Transition — Done state transitions to waiting after configurable delay
Installation
From GitHub Marketplace (recommended)
# Add the marketplace (one-time)
claude plugin marketplace add banyudu/claude-iterm2
# Install the plugin
claude plugin install iterm2@claude-iterm2
The plugin ships pre-bundled JavaScript (dist/) and runs with the system node — no runtime dependencies, no install step.
From Local Clone
git clone [email protected]:banyudu/claude-iterm2.git
cd claude-iterm2 && npm install
Then add it to your local marketplace or symlink it into ~/.claude/plugins/.
Post-Install
Restart Claude Code to activate. Hooks auto-register and tab colors start working immediately.
Optional: Desktop Notifications
brew install terminal-notifier
Usage
Automatic (via hooks)
Just use Claude Code normally. Tab colors update automatically:
- Submit a prompt → blue tab
- Agent asks a question → yellow tab
- Task completes → green tab + notification
- Error occurs → red tab
Setup & Configuration
/iterm2:setup # Interactive feature selection
/iterm2:config # View or change settings
/iterm2:config set badge false # Disable badge text
Settings are stored in ~/.config/claude-iterm2/config.json.
Grid Layout
/iterm2:grid 2x2 # 4-pane grid
/iterm2:grid 3x3 # 9-pane grid
Fork Session
/iterm2:fork # Fork into vertical split (default)
/iterm2:fork --horizontal # Fork into horizontal split
/iterm2:fork --tab # Fork into a new tab
Manual Status Control
/iterm2:status working # Blue tab
/iterm2:status done # Green tab
/iterm2:status reset # Reset to default
Settings
| Setting | Type | Default | Description |
|---|
| tabColor | bool | true | Tab color changes (blue/yellow/green/red) |
| badge | bool | true | Badge text watermark (Working.../Done/etc.) |
| notification | bool | true | Desktop notifications on completion |
| sound | bool | true | Sound notifications |
| gradient | bool | true | Gradient animation for waiting state |
| doneToWaiting | bool | true | Auto-transition from done to waiting |
| doneFlash | bool | true | Brief green flash when work completes |
| errorPulse | bool | true | Short red pulse when a tool fails |
| toolColors | bool | false | Per-tool working colors (reserved for a future release) |
| gradientDuration | number | 60 | Gradient duration (seconds) |
| doneToWaitingDelay | number | 60 | Done-to-waiting delay (seconds) |
| cacheTimeout | number | 300 | Cache expiry timeout in seconds (set 3600 for Claude Max) |
Environment variables (e.g., AI_ENABLE_TAB_COLOR=0) override saved settings.
Effect toggles can also be overridden with AI_ENABLE_DONE_FLASH, AI_ENABLE_ERROR_PULSE, and AI_ENABLE_TOOL_COLORS.
Requirements
- macOS
- iTerm2
- Claude Code
- Node.js
terminal-notifier (optional, for desktop notifications)
License
MIT
