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 → 2x3 or just 6
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.sh on start/stop/input-needed
Sound alerts — afplay (macOS) or paplay (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 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.

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
docs		docs
examples		examples
presets		presets
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
TEST-CHECKLIST.md		TEST-CHECKLIST.md
agentgrid		agentgrid
claude-plugin.json		claude-plugin.json
install.sh		install.sh
package.json		package.json
pane-status.sh		pane-status.sh
test.sh		test.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

agentgrid

Install

Quick Start

Why agentgrid?

Architecture

Features

Grid Layouts

Interactive Setup

Status Labels

Dashboard

Session Save & Restore

Presets

Broadcast

Custom Sounds

Pane Management

Agent Detection & Installation

Supported Agents

All Commands

Keyboard Shortcuts

Configuration

How It Works

Claude Code Plugin

Works With

FAQ

Tests

Contributing

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

agentgrid

Install

Quick Start

Why agentgrid?

Architecture

Features

Grid Layouts

Interactive Setup

Status Labels

Dashboard

Session Save & Restore

Presets

Broadcast

Custom Sounds

Pane Management

Agent Detection & Installation

Supported Agents

All Commands

Keyboard Shortcuts

Configuration

How It Works

Claude Code Plugin

Works With

FAQ

Tests

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages