Skip to content

Claude Code, times four

Run a grid of Claude Code agents.
One command.

claudegrid opens 2 to 16 Claude Code sessions side by side in Konsole, iTerm2, tmux, kitty or WezTerm, on Linux and macOS, and gives each pane its own task, model and git branch.

$ npm install -g @halitsever/claudegrid
claudegrid · my-app · 2x2
▦ claudegrid 1/4 main
> add a /health endpoint
● Reading src/server.ts
● Editing src/routes/health.ts +18
✔ endpoint added, 2 files changed
▦ claudegrid 2/4 tests
> fix the failing tests
● Running npm test
✖ 2 failing in auth.test.ts
✔ 48 passing
▦ claudegrid 3/4 review
> review the uncommitted changes
● Reading git diff, 4 files
! token expiry is never checked
✔ notes in REVIEW.md
▦ claudegrid 4/4 docs
> check the README against the code
● Reading README.md
● Editing README.md +9 -6
✔ docs match the code
Works in
  • Konsolea new tab, D-Bus splits
  • iTerm2macOS, AppleScript
  • tmuxany terminal, over SSH
  • kittysession file
  • WezTermwezterm cli
  • Terminal.appmacOS, tiled windows

Layouts

Any grid, evenly sized

Columns by rows, or just a number of panes. Every split is sized so the panes come out equal, in every terminal. Pane 1 is top left and the rest follow in reading order.

$ claudegrid -l 2x2
1
3
2
4

A task per pane

Hand out the work in one line

Every -p gives the next pane its first prompt. Pick a model for all of them, or set one per pane in a config file. Anything after -- goes to every claude.

Usage guide →
$ claudegrid -m opus \
    -p "add a /health endpoint" \
    -p "fix the failing tests" \
    -p "review the diff"

▦ claudegrid my-app · 2x2 · KDE Konsole
   1 pane-1  ~/my-app
     claude --model opus 'add a /health endpoint'
   2 pane-2  ~/my-app
     claude --model opus 'fix the failing tests'
   3 pane-3  ~/my-app
     claude --model opus 'review the diff'
   4 pane-4  ~/my-app
     claude --model opus
✔ opened a Konsole window

Git worktrees

Every agent on its own branch

Four agents in one checkout overwrite each other. With -w each pane gets its own worktree and branch next to your repo. Open the grid again and every agent picks up where it stopped.

Worktrees guide →
$ claudegrid -w -n 3
created worktree ~/code/app.claudegrid/grid-pane-1 (claudegrid/grid/pane-1)
created worktree ~/code/app.claudegrid/grid-pane-2 (claudegrid/grid/pane-2)
created worktree ~/code/app.claudegrid/grid-pane-3 (claudegrid/grid/pane-3)

$ claudegrid worktrees
claudegrid/grid/pane-1  clean, 3 commits ahead
claudegrid/grid/pane-2  2 changed
claudegrid/grid/pane-3  clean

$ claudegrid worktrees clean
warning: skipping claudegrid/grid/pane-2: 2 uncommitted changes

Presets

Save your team, start it by name

Put pane names, prompts, models and directories in .claudegrid.json. Presets are named variations you start with one word. The JSON Schema gives you autocomplete in your editor.

Presets guide →
// .claudegrid.json
{
  "presets": {
    "review": {
      "model": "opus",
      "panes": [
        { "name": "bugs", "prompt": "Review the diff for bugs" },
        { "name": "security", "prompt": "Look for security problems" },
        { "name": "tests", "prompt": "List changes without a test" }
      ]
    }
  }
}

$ claudegrid review

Desktop app

Prefer clicking? There is an app

Run claudegrid ui or add it to your app menu with claudegrid desktop install. Pick a project, click a pane to give it a task, preview the commands and launch. Everything stays on your machine.

Desktop app guide →
The claudegrid app with a 2x2 grid of panes and a pane editorThe claudegrid app in dark mode

Safe to try

See everything before it runs

--dry-run

Prints the plan and every tmux, Konsole or WezTerm command claudegrid would run. Nothing opens.

doctor

Checks Node.js, Claude Code, git and each terminal, and tells you which one auto picks.

Did you mean

A typo in a flag, preset or config key stops the launch and suggests the right word.

error: .claudegrid.json: panes[1] has an unknown key "promt"
hint: did you mean "prompt"?

Open your first grid

$ npm install -g @halitsever/claudegrid

Node.js 20+, Claude Code and one of the four terminals. Then run claudegrid in any project.

Released under the MIT License.