Troubleshooting
Troubleshooting
Common AgentGrid 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 AgentGrid. | Install Claude Code and re-launch AgentGrid (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 AgentGrid. |
| 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 AgentGrid. |
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. |
| The iPhone app can't reach your computer | AgentGrid isn't running or signed in to the same account, the background service is off, or the relay hasn't connected yet. | Follow the message on the phone, then check Settings → Devices. See Common errors. |
| Settings → Advanced says the background service isn't running | It failed to start. | Select Fix with agent to have a team lead look into it, or open Details for the error and log path. |
| A turn stops with "usage limit reached" | The account used up its plan's allowance for this window. | Pick another model or account from the notice, turn on Auto-switch, or wait for the reset. See Common errors. |
| A Claude pane shows "Sign in to continue" | Claude's sign-in on this computer expired. | Select Sign in to Claude and finish in the terminal that opens. |
| A message shows Not delivered | The agent stopped or restarted before reading it. | Select Retry. |
| A conversation ends with Turn interrupted | The turn was stopped, or the app or agent restarted mid-turn. | Select Continue. |
| AgentGrid opens with "Sessions paused after repeated startup crashes" | The app crashed several times in a row while restoring your sessions. | Choose Keep sessions closed to start without them, then reopen them from File → Reopen Saved Sessions when you're ready. See Logs and diagnostics. |
| CmdMCtrlM mutes the call instead of toggling the overlay | This is the documented behaviour. CmdMCtrlM toggles mute during a call, unless focus is elsewhere in the window; the overlay is opened by clicking the Phone button in a supported pane header. | Use the Phone button to start a call. See Voice mode. |
| Push-to-talk doesn't fire | AgentGrid is not focused, the binding was cleared, or another app has reserved the chosen key. | Focus AgentGrid and hold Cmd;Ctrl;, or record another binding under Settings -> Shortcuts. It is an in-app shortcut, not a system-wide hotkey. |
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 AgentGrid 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 AgentGrid session exited without cleaning up its PTY children. | AgentGrid 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
- Common errors — the messages you might see in a pane, what they mean and what to do.
- 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 phones and paired devices connect, and what telemetry AgentGrid sends.