Troubleshooting

What to try when a setup check fails, an agent seems stuck or you want the welcome tour back.

A setup check failed

Click the fix on the row that failed. Each check comes with one. See Install and first launch for what each fix does.
Click Check again. You can also run the checks from Help › Check Installation… at any time.
For anything else, click Show log, or Copy to copy the error. The log is at ~/.local/state/xagents/logs/installer.log and never contains credentials.
If an upgrade went wrong, Restore previous setup puts back the configuration XAgents backed up before it changed anything.

Still stuck? Send us the log with a short note at vaiditya@xagents.in and we’ll take it from there.

Look for amber. An agent waiting on a permission prompt or a decision appears in Needs you.
Look for a moon. A sleeping agent keeps its place. Select it and press Return or ⌘R.
Look for Reconnect. If a terminal’s connection drops, the tab shows a Reconnect button.
Check the helpers. A parent may be waiting on its helpers. Unfold them with ⇧⌘E.
Run the checks. If background services aren’t running, Help › Check Installation… offers Set up.
Try the other provider. ⌥⌘S continues the task on Claude or Codex in the same tab.

Choose Help › Show Onboarding Again to replay it right away. To show it the next time XAgents opens, run this in Terminal and relaunch:

defaults write local.xagents.desktop xagents.onboarding.v1 -string pending

The first open needs one confirmation. Follow the steps for your macOS version in Install and first launch.