it2ag - Monitor de Agents no iTerm2
mkusaka/it2ag
Dashboard em tempo real para agents de IA no iTerm2
Ver no GitHubAgent que monitora sessões de Claude Code e Codex em tempo real no painel Toolbelt do iTerm2, exibindo status (executando/aguardando/ocioso), repositório git e branch. Permite clicar para focar na aba correta e filtrar sessões por nome, repo ou branch.
Instalação
npx convez-ai mkusaka/it2ag1 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
- Monitorar múltiplas sessões de Claude Code/Codex simultaneamente
- Navegar rapidamente entre agents ativos em diferentes panes
- Rastrear status de execução e contexto git de cada agent
Veredito

Ferramenta muito específica para fluxo de desenvolvimento com Claude Code/Codex no macOS. Útil se você trabalha com múltiplos agents simultâneos, mas requer iTerm2 com Python API e shell integration configurados — não é solução universal.
README
A tradução para o português deste README ainda está na fila.
it2ag
iTerm2 agent monitor for Claude Code and Codex.
Displays a real-time dashboard in iTerm2's Toolbelt sidebar showing all running AI coding agent sessions, their status (running/awaiting user/idle), git repo, and branch.
Features
- Agent detection — Detects Claude Code and Codex processes via process tree inspection
- Running/idle status — Claude Code:
caffeinatechild process; Codex: per-PID IOKit power assertion (pmset) +sandbox-exec/bwrapfast path - Completion acknowledgement — When Claude Code or Codex transitions from running to idle, the card switches to
awaiting useruntil clicked - Git info — Shows repo name and branch for each session
- Repo grouping — Groups sessions by root repository (worktree-aware via
git rev-parse --git-common-dir) - Click to focus — Click a session entry to switch to that iTerm2 pane and clear
awaiting user - Search — Filter sessions by name, repo, branch, or path
- Auto-refresh — Updates every 3 seconds
- Toolbelt auto-open — Automatically opens the Toolbelt panel if it's not already visible
Requirements
- macOS
- iTerm2 with Python API enabled (Settings > General > Magic > Enable Python API)
- iTerm2 Shell Integration (for working directory and git info)
- uv
Installation
Homebrew
brew tap mkusaka/tap
brew install mkusaka/tap/it2ag
uvx from GitHub
Run directly from the git repo without cloning:
uvx --from git+https://github.com/mkusaka/it2ag.git it2ag
Clone and run locally
git clone https://github.com/mkusaka/it2ag.git
cd it2ag
uv run it2ag
Usage
# If installed via Homebrew or uvx
it2ag
# Or from the cloned repo
uv run it2ag
The Toolbelt panel opens automatically. Click any session to focus it, and click an awaiting user card to clear that completion marker.
Options
--version Show the installed version and exit
--port PORT Port for the local web server (default: auto-select)
--install-autolaunch
Install an iTerm2 AutoLaunch wrapper and exit
--force Overwrite an existing AutoLaunch wrapper when used with
--install-autolaunch
Auto-launch on iTerm2 startup
Install the AutoLaunch wrapper with the same command you already use to run it2ag:
# If installed via Homebrew or uvx
it2ag --install-autolaunch
# Or from the cloned repo
uv run it2ag --install-autolaunch
This writes ~/Library/Application Support/iTerm2/Scripts/AutoLaunch/it2ag.py.
If you run setup from a Homebrew-installed it2ag, the wrapper resolves
it2ag from PATH first, then falls back to common install locations such as
/opt/homebrew/bin/it2ag and /usr/local/bin/it2ag.
If you run setup from a cloned repo via uv run it2ag --install-autolaunch,
the wrapper becomes project-aware: it prefers <repo>/.venv/bin/it2ag, then
falls back to uv --project <repo> run it2ag.
If ~/Library/Application Support/iTerm2/Scripts/AutoLaunch/it2ag.py already
exists and you want it2ag to replace it, rerun the command with --force.
Release
- Update
versioninpyproject.tomlandsrc/it2ag/__init__.py. - Commit the release changes and push them to
main. - Create and push a
vX.Y.Ztag. - The
Releaseworkflow builds macOS app directories for Apple Silicon and Intel, publishes them to GitHub Releases, and dispatches a formula update tomkusaka/homebrew-tap.
How it works
- A local aiohttp web server serves an HTML dashboard
- The dashboard is registered as an iTerm2 Toolbelt WebView tool via the Python API
- Agent detection scans the process tree (
ps -eo pid,ppid,comm) to findclaude/codexprocesses and maps them to iTerm2 sessions - Running state detection:
- Claude Code: checks for
caffeinatechild process (spawned during active turns) - Codex: parses
pmset -g assertionsfor per-PID IOKit power assertions ("Codex is running an active turn"), withsandbox-exec/bwrapchild check as a fast path. Works with all sandbox modes includingdanger-full-access
- Claude Code: checks for
- The dashboard keeps a small per-session transition cache so
running -> idleis rendered asawaiting useruntil the card is clicked - Git info is resolved per-session using GitPython, with worktree grouping via
common_dir
Development
uv sync --group dev
# Build local app directory
./scripts/build-binary.sh
# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/
# Type check
uv run mypy src/
# Test
uv run pytest -v
License
GPL-2.0