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:

1. Grid size → 2x3 or just 6
2. Default agent → claude
3. Configure individual panes (names, agents)
4. 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.

1. Grid engine — creates tmux panes using split-window + select-layout tiled
2. Status system — custom tmux options (@pane_status, @pane_label) for per-pane metadata
3. Agent hooks — Claude Code/Codex hooks call pane-status.sh on start/stop/input-needed
4. Sound alerts — afplay (macOS) or paplay (Linux), works through DND/Focus mode
5. Session persistence — JSON snapshots of pane layout, agent type, directory, conversation ID
6. Agent detection — walks process tree (ps -o args) to identify agents behind node processes

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.

License

MIT — see LICENSE.