Troubleshooting
Troubleshooting
Common Agent Grid problems and the fixes that resolve them.
This is the quick-reference matrix for the issues users hit most often. Each row points at a root cause and a concrete fix; deeper pages cover logs, updates, and security.
Problem → cause → fix
| Problem | Likely cause | Fix |
|---|---|---|
| Spawning a Claude pane fails with "Claude CLI is not installed" | The claude CLI isn't on PATH for the user account that launched Agent Grid. | Install Claude Code and re-launch Agent Grid (so it picks up the updated PATH). |
| Spawning a Codex pane fails with "Codex CLI is not installed" | The codex CLI isn't on PATH. | npm install -g @openai/codex, then re-launch Agent Grid. |
| Spawning an Antigravity pane fails with "Antigravity CLI (agy) is not installed" | The agy CLI isn't on PATH. | Install it from antigravity.google, then re-launch Agent Grid. |
read_dev_server_url never returns a URL for a terminal you just spawned | The dev server hasn't printed a recognizable URL yet, or it's writing the URL to a file rather than stdout. | Use wait_for_terminal_pattern with a pattern that you know the server prints (for example Local:\s+https?:// for Vite, Listening on for Express). Check the result variant before reporting success — matched, timedOut, exited, or error. |
| Mobile pairing fails — the QR scan never completes | The phone and desktop aren't on the same local network, the desktop's mobile-bridge HTTP server is blocked by a firewall, or the device store can't be written. | Confirm both devices are on the same Wi-Fi, allow incoming connections on the local-network ports the desktop opens at launch, and check the logs for mobile-bridge errors. |
| CmdMCtrlM mutes the call instead of toggling the overlay | This is the documented behaviour. CmdMCtrlM toggles mute inside the open call overlay; the overlay is opened by clicking the Phone button in a Claude pane's header, not by a global shortcut. | Use the Phone button to start a call. See Voice mode. |
| Push-to-talk doesn't fire on Linux | The session is Wayland, and the focused window is a native-Wayland surface that doesn't forward the global hotkey. | Click the dictation indicator manually as a fallback, or switch focus to an X11/XWayland window. The push-to-talk key is rebindable from Settings. |
Terminal pane shows bash: command not found for shell built-ins, or no prompt appears | The PTY started against a shell that didn't load the user's profile, or node-pty failed to attach to a TTY. | Confirm the user's default shell is set (echo $SHELL) and that the shell has a sane rc file. If the pane shows nothing, kill and respawn the terminal pane. |
| Two copies of Agent Grid refuse to run | The single-instance lock is preventing a second copy from booting against the same userData. | Quit the existing instance fully (check the tray / dock), or launch a dev build — dev electron uses a -dev userData suffix so it can run alongside packaged. |
Orphan claude / codex processes after a crash | A previous Agent Grid session exited without cleaning up its PTY children. | Agent Grid runs a stale-child reaper at launch that SIGTERMs orphan PTYs from a previous run. Restart the app; the reaper will clean up on boot. |
Where to go next
- Logs and diagnostics — where app data lives and what to capture when filing a bug.
- Updates — how auto-update works and how to force a reinstall.
- Security and privacy — where credentials live, how mobile pairing is authenticated, and what telemetry Agent Grid sends.