AgentGridAgentGrid Docs
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

ProblemLikely causeFix
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 spawnedThe 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 computerAgentGrid 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 runningIt 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 deliveredThe agent stopped or restarted before reading it.Select Retry.
A conversation ends with Turn interruptedThe 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 overlayThis 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 fireAgentGrid 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 appearsThe 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 runThe 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 crashA 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.

On this page

Ask AI

Ask a question about AgentGrid. Answers come from these docs, with links to the pages they use.

AI answers can be wrong. Check the linked pages.