Tab Monitor
Parassharmaa/tab-monitor
Classifica e colore abas do iTerm2 por estado de trabalho com IA
Ver no GitHubAgente orquestrador para iTerm2 que monitora e classifica automaticamente o estado de cada aba (precisa atenção / quase pronto / PR aberto / PR mergeado) usando Claude, recolore-as e valida merges via GitHub CLI. Executa como loop de fundo a cada 5 minutos e integra-se como skill do Claude Code.
Instalação
npx convez-ai Parassharmaa/tab-monitor1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Organizar visualmente o estado de múltiplos projetos abertos no terminal
- Validar automaticamente quando PRs foram mergeados e abas podem ser fechadas
- Accelerar o fluxo de trabalho em desenvolvimento com feedback visual automático
Veredito

Ferramenta altamente especializada para desenvolvedores em macOS que usam iTerm2. Combina automação inteligente com integração GitHub para manter ordem visual nos workflows paralelos, mas requer setup manual e API local do iTerm2.
README
A tradução para o português deste README ainda está na fila.
tab-monitor
An iTerm2 orchestration agent that watches the tabs of all your iTerm windows,
classifies each tab's state with claude -p, and recolors the tab. Tab order is left
alone by default (set TM_REORDER=1 to also sort tabs red → blue within each window).
| Color | Meaning |
|---|---|
| 🔴 red | needs your attention now / work in progress / agent waiting on you / error |
| 🟡 yellow | nearly done — finishing up, tests running, about to open a PR |
| 🟢 green | work done, but its PR is not merged (open/draft/awaiting review) — verified via gh |
| 🔵 blue | work done and its PR is merged (verified via gh) — this tab can be closed |
| (none) | not a recognizable work session — left alone |
green-vs-blue is authoritative, not guessed: the model decides done vs not and extracts the
tab's own deliverable PR number; then gh pr view <n> decides green (not merged) vs blue (merged).
How it works
It connects to the iTerm2 Python API over iTerm's local Unix socket (the only way to
reach tabs programmatically — escape codes can't reach them from a non-TTY process). Each
pass it: enumerates every iTerm window → captures every tab's visible screen → hashes it
(unchanged tabs are skipped, no LLM call) → sends the changed ones to claude -p (sonnet,
custom system prompt, tools disabled) → for "done" tabs, reads the tab's working dir and runs
gh pr view to decide green-vs-blue → applies the tab color. (Reordering red→blue per window is
opt-in via TM_REORDER=1.)
- PR-gated blue (
TM_PR_CHECK=1, default) — a tab is blue only when its deliverable PR is confirmed merged viagh; otherwise a done tab is green. Needsghauthed and iTerm shell integration (so the tab reports itspath). The branch PR is checked first; if the tab is on a shared branch (e.g.dev) with no branch PR, the model-extracted PR number is verified instead. SetTM_PR_CHECK=0to skipghand let the model alone decide green/blue. - All windows by default — set
TM_WINDOW_IDto pin it to a single window instead. (iTerm2 only; other terminal apps like Terminal.app aren't reachable via this API.) - Bounded concurrency — at most
TM_CONCURRENCY(6)claudecalls run at once, even with many tabs. - Self-skipping — it reads its own
ITERM_SESSION_IDand never recolors the tab it runs in, in whichever window that is.
Install as a Claude Code skill
git clone https://github.com/Parassharmaa/tab-monitor.git
cd tab-monitor
./install.sh # symlinks skill/ into ~/.claude/skills/tab-monitor
Then start the 5-minute background loop (and manage it) with either the skill or the launcher:
# in Claude Code: /tab-monitor (defaults to "start")
bash ~/.claude/skills/tab-monitor/scripts/monitor.sh start # start the loop
bash ~/.claude/skills/tab-monitor/scripts/monitor.sh status # running? + recent passes
bash ~/.claude/skills/tab-monitor/scripts/monitor.sh stop # stop it
Run without installing
# one dry pass — classify + log, change nothing (start here)
TM_DRY_RUN=1 TM_ONCE=1 ./run.sh
# run for real, looping every 5 min, in a dedicated tab
./run.sh
# every 10 min, no reordering
TM_INTERVAL=600 TM_REORDER=0 ./run.sh
Config (env vars)
| Var | Default | Meaning |
|---|---|---|
TM_INTERVAL | 300 | seconds between passes |
TM_MODEL | sonnet | model for classification (haiku = cheaper/faster, less accurate) |
TM_REORDER | 0 | 1 sort tabs red→blue, 0 off (default: leave order alone) |
TM_DRY_RUN | 0 | 1 classify + log only |
TM_ONCE | 0 | 1 single pass then exit |
TM_MAX_LINES | 60 | screen lines fed to the classifier |
TM_CONCURRENCY | 6 | max simultaneous claude/gh calls |
TM_PR_CHECK | 1 | 1 blue only if PR merged (via gh); 0 let the model decide |
TM_WINDOW_ID | (all) | pin to one window id (default: every window) |
Cost
Only tabs whose screen changed since the last pass are sent to the model, so a quiet
window costs nothing. Each classified tab is one short claude -p call (default sonnet
for accuracy; set TM_MODEL=haiku to cut cost). Note: live agent TUIs (codex/Claude)
redraw spinner/timer lines every pass, so their hash keeps changing and they get
re-classified each cycle — the biggest cost driver. Stripping those volatile lines before
hashing is a planned optimization.
Run it in the background
skill/scripts/monitor.sh start runs it as a nohup background loop (pid + log under
.state/). It does not survive a reboot — for that, load it as a launchd agent
(StartInterval=300 for a cron-style one-shot, or KeepAlive for the daemon).
Layout
README.md
install.sh # symlink skill/ into ~/.claude/skills/
run.sh # run once / loop without installing
skill/
SKILL.md # Claude Code skill definition
scripts/
tab_monitor.py # the agent (capture → classify → color loop)
monitor.sh # start/stop/restart/status/once launcher
examples/
demo_make.py # build a 4-tab demo window with synthetic state
verify_dump.py # dump what the classifier saw for a tab (debugging)