Troubleshooting
Common issues and safe first steps. When in doubt, your installed version keeps working. Most fixes are non-destructive.
Updates
An update check failed
Usually a temporary network or feed issue. Open Settings → Software Update and select Retry once connectivity is restored. Downloaded updates are checksum-verified, so a failed check never applies a bad update.
It says "up to date" but I expected a new version
The stable channel may not be newer than what you have yet. New releases roll out to the stable feed; if you just saw a release announced, give it a few minutes and Check now again.
I chose Restart to update but it didn't relaunch
Reopen Agent Relay from Applications. Your previous version stays installed and your chats and settings are preserved. If it recurs, capture the version and reopen, no data is lost by staying on the current version.
Agents
An agent shows as unavailable
Agent Relay only lists agent CLIs found on your PATH. Install the agent (for example Claude Code, Codex, Gemini, or Kimi), then reopen Settings → Agents to re-scan. The row lights up once the CLI is detected.
A chat won't start
Confirm the selected agent is available in Settings → Agents, and that it's signed in / authorized in its own CLI. Agent Relay launches the agent as a managed run, if the underlying CLI can't run, the chat can't start.
Installation
The app won't open after download
Agent Relay is notarized, so it should open without warnings. Make sure you dragged it into Applications and are opening it from there (not from inside the mounted disk image). Re-download from the Download button if the file was interrupted.
Getting help
If something isn't covered here, open an issue on GitHub with your app version (Settings → Software Update), macOS version, and what you saw.