AgentGrid
naman10parikh/agentgrid
Spawn grids de agentes de IA em um comando com status visual e alertas
Ver no GitHubFerramenta que cria grids de agentes de IA em paralelo no terminal, permitindo executar múltiplos Claude, Codex, Gemini ou qualquer comando em layout grid com status visual e alertas sonoros. Gerencia sessões, presets e reutiliza históricos de conversas sem dependências além de tmux.
Instalação
npx convez-ai naman10parikh/agentgrid1 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
- Executar múltiplas tarefas de coding em paralelo em um só grid
- Coordenar trabalho de agentes diferentes (Claude, Codex, Gemini) simultaneamente
- Monitorar status de múltiplos agentes com cores e alertas sonoros
- Salvar e restaurar configurações inteiras com históricos de sessão
Veredito

AgentGrid resolve um problema real de orquestração paralela de agentes IA no terminal. Abordagem pragmática (tmux puro, bash, sem servidor) que funciona para quem já vive no CLI, mas requer familiaridade com terminal e tmux para explorar todo o potencial.
README
A tradução para o português deste README ainda está na fila.
agentgrid
Your AI agents deserve a proper office.
One command. Six agents. All working in parallel.
npx agentgrid 2x3 claude
┌──────────────┬──────────────┬──────────────┐
│ ⚡ Agent 1 │ ⚡ Agent 2 │ ⚡ Agent 3 │
│ fixing auth │ writing tests│ updating docs│
├──────────────┼──────────────┼──────────────┤
│ ✅ Agent 4 │ ⏳ Agent 5 │ ⚡ Agent 6 │
│ done — 3min │ needs input │ refactoring │
└──────────────┴──────────────┴──────────────┘
agentgrid creates grids of terminal panes, launches your AI coding agent in each one, and shows you who's working (blue), who's done (green), and who needs you (yellow) — with sound alerts.
Works with Claude Code, Codex, Gemini CLI, Aider, Goose, Cline, Hermes, Copilot, Cursor, or literally any terminal command.
Install
npm install -g agentgrid
Or with curl:
curl -fsSL https://raw.githubusercontent.com/naman10parikh/agentgrid/main/install.sh | bash
Installs tmux (if needed), configures hooks, sets up sounds. 60 seconds.
Requirements: bash, tmux, python3 · Supports: macOS · Linux · Windows (WSL)
Quick Start
# Same agent in every pane
agentgrid 2x3 claude
# Interactive wizard — pick agents per pane, save as preset
agentgrid setup
# Launch a saved configuration
agentgrid launch dev-sprint
agentgrid auto-detects tmux. If you're not inside a tmux session, it creates one for you.
Why agentgrid?
You have 6 tasks. You could run them sequentially in one Claude session (slow), or open 6 terminal tabs manually (tedious). agentgrid gives you:
- One command to spawn any grid layout (2x2, 3x5, 5x5)
- Color-coded status so you know who needs attention at a glance
- Sound alerts when an agent finishes or needs input (works through DND)
- Save & restore entire grid configurations with conversation history
- Zero dependencies — built on tmux, the tool you already have
Architecture
┌─────────────────────────────────────────────────┐
│ agentgrid CLI │
│ (1,400 lines of bash — no daemon, no server) │
├────────────┬────────────┬───────────────────────┤
│ Grid │ Session │ Status │
│ Engine │ Manager │ System │
│ │ │ │
│ split │ save │ @pane_status │
│ layout │ restore │ @pane_label │
│ equalize │ presets │ color-coded │
├────────────┴────────────┴───────────────────────┤
│ tmux │
│ panes · sessions · custom options · hooks │
├─────────────────────────────────────────────────┤
│ Terminal Emulator │
│ Ghostty · iTerm2 · Kitty · WezTerm · Terminal │
└─────────────────────────────────────────────────┘
No Electron. No WebSocket server. No process manager. Just tmux — the battle-tested terminal multiplexer that's already on your machine.
Features
Grid Layouts
agentgrid 2x2 claude # 4 panes
agentgrid 3x4 codex # 12 panes
agentgrid 5x5 # 25 empty panes (up to 10x10)
Panes auto-equalize. Re-equalize anytime: agentgrid equalize
Interactive Setup
agentgrid setup
Visual wizard with grid preview. 4 steps:
- Grid size →
2x3or just6 - Default agent →
claude - Configure individual panes (names, agents)
- Save as preset (optional)
Status Labels
| Status | Label | Color | Sound |
|---|---|---|---|
| Working | ⚡ WORKING | Blue | — |
| Needs input | ⏳ WAITING | Yellow | Tink |
| Done | ✅ DONE | Green | Glass |
Status updates automatically via agent hooks (Claude Code, Codex, OpenCode). Other agents use exit code detection.
Dashboard
agentgrid dashboard # Snapshot with controls
agentgrid dashboard live # Auto-refreshing every 2s
Table view of all panes with name, agent, and status. Quick action menu included.
Session Save & Restore
agentgrid save my-grid # Save everything
agentgrid restore my-grid # Restore + resume conversations
agentgrid restore my-grid --no-start # Layout only, no agents
Save captures each pane's agent, directory, name, and conversation session ID. Restore resumes the exact conversation — not just the most recent one.
Per-agent resume: Claude (--resume <id>), Codex (codex resume <id>), Gemini (--resume latest), Goose (session resume --last).
Presets
agentgrid preset list # See saved presets
agentgrid launch dev-sprint # Launch one
agentgrid preset show mixed-agents # View details
agentgrid preset delete old-setup # Remove
3 built-in: dev-sprint (4 panes), mixed-agents (6 panes), research-swarm (9 panes).
Broadcast
agentgrid broadcast "git pull && pnpm test" # Send to ALL panes
agentgrid broadcast "/status" # Send a slash command
Custom Sounds
agentgrid sound done ~/Music/tada.mp3 # Your own audio
agentgrid sound waiting system:Hero # macOS built-in
agentgrid sound test # Preview all 3
agentgrid sound off # Silence
MP3, WAV, AIFF, M4A, OGG. Plays through DND/Focus mode via afplay (macOS) or paplay (Linux).
Pane Management
agentgrid name "Auth Worker" # Name current pane (locked)
agentgrid add right claude # Add pane to grid
agentgrid swap up # Reorder panes
agentgrid equalize # Even out sizes
agentgrid kill # Clear to 1 pane
agentgrid status # All pane statuses
agentgrid status --json # Machine-readable (for scripts)
Agent Detection & Installation
agentgrid agents # Show installed/available
agentgrid install codex # Install one
agentgrid install-all # Install all missing
Supported Agents
| Agent | Command | Install | Auto Status |
|---|---|---|---|
| Claude Code | claude | npm i -g @anthropic-ai/claude-code | Yes (hooks) |
| Codex | codex | npm i -g @openai/codex | Yes (hooks) |
| Gemini CLI | gemini | npm i -g @google/gemini-cli | Exit code |
| Aider | aider | pip install aider-chat | Exit code |
| OpenCode | opencode | npm i -g opencode | Yes (hooks) |
| Goose | goose | brew install goose | Exit code |
| Cline | cline | npm i -g @anthropic-ai/cline | Exit code |
| Hermes | hermes | npm i -g hermes-cli | Exit code |
| Copilot | copilot | npm i -g @github/copilot | Exit code |
| Cursor | cursor | brew install --cask cursor | Exit code |
| Any command | <your-cmd> | — | Exit code |
agentgrid doesn't restrict what you run. Any terminal command works as an agent.
All Commands
GRIDS
agentgrid ROWSxCOLS [agent] Create grid (e.g. 2x3 claude)
agentgrid setup Interactive wizard with grid preview
PRESETS
agentgrid launch <name> Launch a saved preset
agentgrid preset list Show presets
agentgrid preset show <name> View details
agentgrid preset delete <name> Delete
SESSIONS
agentgrid save [name] Save grid + names + conversations
agentgrid restore [name] Restore grid + resume chats
agentgrid restore [name] --no-start Layout only (no agents)
AGENTS
agentgrid agents Detect installed agents
agentgrid install <agent> Install one
agentgrid install-all Install all missing
CONTROL
agentgrid dashboard Grid map + controls
agentgrid dashboard live Auto-refreshing (2s)
agentgrid status All pane statuses
agentgrid status --json Machine-readable output
agentgrid add [right|down] [agent] Add pane to grid
agentgrid swap [up|down] Swap pane position
PANES
agentgrid name <name> Name current pane (locked)
agentgrid broadcast <text> Send to all panes
agentgrid equalize Even out sizes
agentgrid kill Clear to 1 pane
SOUNDS
agentgrid sound Show current sounds
agentgrid sound <event> <file> Set sound
agentgrid sound test Preview all
agentgrid sound off Disable
SETUP
agentgrid start [session] Start/attach tmux
agentgrid terminal-setup Configure Claude panes
agentgrid tips Usage tips
agentgrid update Self-update from GitHub
agentgrid detach Exit (grid keeps running)
agentgrid version Show version
agentgrid help Show help
Keyboard Shortcuts
| Keys | Action |
|---|---|
| Option+H/J/K/L | Navigate panes (vim-style) |
| Option+Arrow | Navigate panes |
| Click | Switch to pane |
| Ctrl+A | | Split right |
| Ctrl+A - | Split down |
| Ctrl+A z | Zoom (fullscreen toggle) |
| Ctrl+A E | Equalize sizes |
| Ctrl+A { } | Swap pane up/down |
| Ctrl+A Space | Cycle layouts |
| Ctrl+A c | New window |
| Ctrl+A 1-9 | Switch window |
| Ctrl+A d | Detach (runs in background) |
| Drag borders | Resize panes with mouse |
Configuration
~/.agentgrid/
├── config.json # Global settings (sounds, defaults)
├── presets/ # Saved grid configurations
│ ├── dev-sprint.json
│ ├── mixed-agents.json
│ └── research-swarm.json
├── sessions/ # Saved session state (save/restore)
└── sounds/ # Custom sound files
Example config.json:
{
"default_agent": "claude",
"sounds": {
"done": "/System/Library/Sounds/Glass.aiff",
"waiting": "/System/Library/Sounds/Tink.aiff",
"sub_agent": "/System/Library/Sounds/Purr.aiff"
}
}
How It Works
agentgrid is ~1,400 lines of bash. No daemon, no server, no background process.
- Grid engine — creates tmux panes using
split-window+select-layout tiled - Status system — custom tmux options (
@pane_status,@pane_label) for per-pane metadata - Agent hooks — Claude Code/Codex hooks call
pane-status.shon start/stop/input-needed - Sound alerts —
afplay(macOS) orpaplay(Linux), works through DND/Focus mode - Session persistence — JSON snapshots of pane layout, agent type, directory, conversation ID
- Agent detection — walks process tree (
ps -o args) to identify agents behindnodeprocesses
Claude Code Plugin
agentgrid ships as a Claude Code plugin. Add it to any project:
{
"name": "agentgrid",
"hooks": {
"UserPromptSubmit": { "command": "agentgrid-pane-status running" },
"PermissionRequest": { "command": "agentgrid-pane-status needs-input" },
"Stop": { "command": "agentgrid-pane-status done" }
}
}
This enables automatic status updates — panes turn blue when working, yellow when waiting for permission, green when done.
Works With
Terminals: Ghostty, iTerm2, Terminal.app, Kitty, WezTerm, Alacritty, Windows Terminal (WSL)
IDEs: Cursor (integrated terminal), VS Code (integrated terminal)
OS: macOS, Linux (Ubuntu, Fedora, Arch), Windows (via WSL)
FAQ
Q: Do I need tmux installed? A: agentgrid installs tmux automatically if it's missing (via Homebrew on macOS, apt/dnf/pacman on Linux).
Q: Can I mix different agents in the same grid?
A: Yes. Use agentgrid setup to assign different agents per pane, or start with a uniform grid and override individual panes.
Q: What happens when I close my terminal?
A: The tmux session keeps running in the background. Reattach with agentgrid start or tmux attach.
Q: Can I use this with my own CLI tool?
A: Yes. Any command works: agentgrid 2x2 "python my_agent.py". agentgrid doesn't restrict what runs in each pane.
Q: How does save/restore work with conversations?
A: agentgrid save captures each pane's conversation session ID by walking the process tree. agentgrid restore uses agent-specific resume flags (--resume for Claude, codex resume for Codex, etc.) to pick up where you left off.
Q: What's the maximum grid size? A: 10x10 (100 panes). In practice, 3x3 or 4x4 is the sweet spot for most monitors.
Q: Does it work in VS Code / Cursor terminal?
A: Yes. The integrated terminal supports tmux. Run agentgrid 2x2 claude directly.
Tests
cd tools/agentgrid && bash test.sh
30+ tests covering file structure, version consistency, help output, preset validation, package.json fields, grid pattern matching, security (no eval injection), and command execution.
Contributing
See CONTRIBUTING.md for guidelines.
See Also
- agentbench — Benchmark AI coding agents head-to-head on real tasks
- agentmoney — Track what your AI agents cost across providers
- claude-harness — Production-grade Claude Code setup with hooks, skills, and memory
License
MIT — see LICENSE.