Getting started

Install CodeGrid, connect your agents, and run your first parallel session.

Requirements

  • macOS 13 Ventura or later
  • Apple Silicon (M1, M2, M3, or M4)
  • The agent CLIs you want to use (see below) — CodeGrid launches them, it doesn't bundle them

1. Install CodeGrid

Download the latest release, open it, and drag CodeGrid to your Applications folder. The app is signed with an Apple Developer ID and notarized by Apple, so it opens without Gatekeeper warnings.

Download for Mac

2. Install your agents

CodeGrid runs the agent CLIs you already use. Install any you want — CodeGrid auto-detects them on your PATH (it also adds common locations like /opt/homebrew/bin and ~/.local/bin).

Claude Codedocs →
npm i -g @anthropic-ai/claude-code
Codexdocs →
npm i -g @openai/codex
Gemini CLIdocs →
npm i -g @google/gemini-cli
Cursordocs →
curl https://cursor.com/install -fsS | bash

Each agent authenticates with its own account; CodeGrid stores no keys. A plain shell needs nothing — it uses your $SHELL.

3. Your first session

  1. Press ⌘N to open a new session.
  2. Pick an agent (or a shell) and choose a project folder.
  3. Open more sessions and drag them around the canvas — zoom out to see everything.
  4. Press ⌘B to broadcast one prompt to every pane.
  5. Press ⌘K for the command palette — switch workspaces, run Git, jump to panes.

Keyboard shortcuts

⌘ NNew session
⌘ KCommand palette
⌘ BBroadcast to all panes
⌘ ⏎Maximize / restore pane
⌘ 1–9Jump to pane
⌘ ←→Navigate panes
⌘ ⇧ ←→Swap pane positions
⌘ SToggle sidebar
⌘ TabNext workspace
⌘ ,Settings

Troubleshooting

An agent won't launch

Make sure its CLI is installed and on your PATH (run which claude, which codex, etc. in a terminal). Cursor's binary is cursor-agent.

A session ended unexpectedly

Closing a pane terminates that session's whole process group. Use "Restart session" on the pane, or reopen with ⌘N.

Still stuck?

Open an issue on GitHub or email admin@codegrid.dev.