Skip to content

Configuration ​

claudegrid reads two optional JSON files:

FileScope
~/.config/claudegrid/config.jsonyour defaults on this machine
.claudegrid.json (or claudegrid.json)the project. claudegrid looks in the current directory and every parent

Run claudegrid init to create a project config with examples. Use -c <file> to point at another file.

Example ​

json
{
  "$schema": "https://halitsever.github.io/claudegrid/schema.json",
  "model": "sonnet",
  "args": ["--permission-mode", "acceptEdits"],
  "panes": [
    { "name": "api", "dir": "server", "prompt": "Add rate limiting to the public endpoints" },
    { "name": "web", "dir": "web" },
    { "name": "tests", "prompt": "Run the test suite and fix whatever fails" },
    { "name": "review", "model": "opus", "prompt": "Review the uncommitted changes" }
  ]
}

The $schema line gives you autocomplete and checks in VS Code, JetBrains IDEs and any editor with a JSON language server.

Grid options ​

KeyTypeDefaultWhat it does
layoutstring"2x2"COLSxROWS or a pane count. Wins over a numeric panes
panesnumber or array4how many panes, or one entry per pane
modelstring--model for every pane
argsstring[]extra Claude Code flags for every pane
worktreesbooleanfalseone git worktree per pane
backendstring"auto"auto, konsole, iterm2, tmux, kitty, wezterm or terminal
commandstring"claude"program each pane runs
keepShellbooleantrueopen your shell when the program exits
newTabbooleantrueopen the grid as a tab in the terminal you run claudegrid in
trustbooleantruemark every pane folder as trusted in Claude Code, so it skips the trust question
dirstringbase directory for every pane, relative to the config file

Pane options ​

Each entry in panes is either an object or a string. A string is shorthand for { "prompt": "..." }.

KeyWhat it does
nametitle of the pane, and its branch name with worktrees. Must be unique
promptfirst message sent to Claude
modeloverrides the grid model
argsClaude Code flags for this pane only
dirworking directory, relative to the config file

How settings combine ​

From lowest to highest priority:

  1. user config
  2. project config
  3. the preset you picked
  4. command line flags

A later layer replaces a value from an earlier one. args is the exception: the args from every layer are added together, so a preset can add flags without repeating the project's.

Each pane's command line is built in this order:

txt
claude <args> --model <model> <pane args> <flags after --> <prompt>

Mistakes are caught early ​

claudegrid checks the whole config before it opens anything, and it points at the exact key:

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

Released under the MIT License.