Troubleshooting
The usual suspects, and how to fix them.
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. CodeGrid also checks /opt/homebrew/bin and ~/.local/bin.
A session ended unexpectedly
Closing a pane terminates that session's whole process group. Use Restart on the pane, or reopen with ⌘N.
I can only see one pane / panes look missing
The canvas may be zoomed or panned. Click FIT (top-right of the canvas) to bring everything into view, or AUTO to re-tile every pane.
My agents don't have the collaboration tools
Run /mcp in the pane and look for codegrid-agent-bus. If it's missing, enable collaboration (onboarding, or the bus setup command), then open a fresh pane with ⌘N — new panes pick the tools up automatically. See The Agent Bus.
“Can't reach CodeGrid” from an agent
The CodeGrid app must be running — the agent bus talks to it over a local socket (~/.codegrid/socket).
The editor or code viewer looks broken
Make sure you're on the latest version (Settings → Check for Updates). If it persists, report it below.
Still stuck?
Open an issue on GitHub or email admin@codegrid.dev.