convez.ai
SkillAutomaçãoAvançado
Parassharmaa

Tab Monitor

Parassharmaa/tab-monitor

Classifica e colore abas do iTerm2 por estado de trabalho com IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Agente 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-monitor

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

ColorMeaning
🔴 redneeds your attention now / work in progress / agent waiting on you / error
🟡 yellownearly done — finishing up, tests running, about to open a PR
🟢 greenwork done, but its PR is not merged (open/draft/awaiting review) — verified via gh
🔵 bluework 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 via gh; otherwise a done tab is green. Needs gh authed and iTerm shell integration (so the tab reports its path). 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. Set TM_PR_CHECK=0 to skip gh and let the model alone decide green/blue.
  • All windows by default — set TM_WINDOW_ID to 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) claude calls run at once, even with many tabs.
  • Self-skipping — it reads its own ITERM_SESSION_ID and 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)

VarDefaultMeaning
TM_INTERVAL300seconds between passes
TM_MODELsonnetmodel for classification (haiku = cheaper/faster, less accurate)
TM_REORDER01 sort tabs red→blue, 0 off (default: leave order alone)
TM_DRY_RUN01 classify + log only
TM_ONCE01 single pass then exit
TM_MAX_LINES60screen lines fed to the classifier
TM_CONCURRENCY6max simultaneous claude/gh calls
TM_PR_CHECK11 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)
Ver o original no GitHub

Bom para

Relacionados