@namanparikh/agentgrid
Advanced tools
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.
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)
# 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.
You have 6 tasks. You could run them sequentially in one Claude session (slow), or open 6 terminal tabs manually (tedious). agentgrid gives you:
┌─────────────────────────────────────────────────┐
│ 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.
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
agentgrid setup
Visual wizard with grid preview. 4 steps:
2x3 or just 6claude| 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.
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.
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).
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).
agentgrid broadcast "git pull && pnpm test" # Send to ALL panes
agentgrid broadcast "/status" # Send a slash command
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).
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)
agentgrid agents # Show installed/available
agentgrid install codex # Install one
agentgrid install-all # Install all missing
| 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.
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
| 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 |
~/.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"
}
}
agentgrid is ~1,400 lines of bash. No daemon, no server, no background process.
split-window + select-layout tiled@pane_status, @pane_label) for per-pane metadatapane-status.sh on start/stop/input-neededafplay (macOS) or paplay (Linux), works through DND/Focus modeps -o args) to identify agents behind node processesagentgrid 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.
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)
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.
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.
See CONTRIBUTING.md for guidelines.
MIT — see LICENSE.
FAQs
Spawn a grid of AI coding agents in one command
We found that @namanparikh/agentgrid demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket Firewall blocks malicious VS Code and Open VSX extensions before install, protecting developers from compromised editor marketplaces.
Research
More than 140 Mastra npm packages were compromised in a supply chain attack that used a typosquatted dependency to deliver a cross-platform infostealer during installation.
Research
/Security News
A new npm package tests AI malware scanners with prompt injection, safety-triggering comments, context flooding, and obfuscated JavaScript.