Troubleshooting

Start with two checks. Run screen -ls to see whether PRIMA Bot is running, then read the log with tail ~/Library/Logs/prima-bot-remote-server/launchd.log.

Messages and Symptoms

What you see	What to do
Your Mac is missing from the Code list in the Claude app	Run screen -ls. If prima-bot is missing, read the log and restart PRIMA Bot
WORKSPACE_DIR is not set in the log	Add WORKSPACE_DIR to the settings file, then restart PRIMA Bot
Workspace directory not found in the log	The folder in WORKSPACE_DIR has moved or been renamed. Correct the path and restart PRIMA Bot
Claude binary not found or not executable in the log	Set CLAUDE_BIN to the output of which claude, then restart PRIMA Bot
screen session 'prima-bot' already running; waiting in the log	A server with that name is already running, often one you started by hand. Close it, or leave it, and the launcher takes over when it ends
Remote Control requires claude.ai subscription auth.	Claude Code is signed in with an API key or token. Run claude auth logout, then claude auth login, and choose your subscription account
“Remote Control isn’t enabled for this account”	On a Team or Enterprise plan, ask the account Owner to switch on Remote Control. On Pro or Max, sign out and sign in again
The Mac restarted and PRIMA Bot is offline	Log in to the Mac. PRIMA Bot starts within a minute
Connector tools fail in phone sessions but work at the desk	A connector needs a program outside the launcher’s PATH. Add its folder to the PATH line in the launcher source and run ./install.sh again
A session from the phone asks a question nobody sees	Turn on the two push settings in /config, as Step 3 of Installing PRIMA Bot shows, and allow notifications for the Claude app

A Connector Sign-In Disappears

A connector you signed in to, such as a hosted mail or design service, may ask you to sign in again in every Claude Code window at once. This has happened after an automatic Claude Code update while PRIMA Bot kept older sessions running.

1. Restart PRIMA Bot after each Claude Code update, with the restart command in Everyday Controls.
2. Sign in to the connector again from a session at the desk.

The Mac Goes to Sleep

PRIMA Bot keeps the Mac awake while it runs. A MacBook still sleeps when its lid closes, so leave the lid open and keep it plugged in. If a desktop Mac sleeps, run screen -ls to check that PRIMA Bot is running.

The Internet Was Down

Remote Control stops after about ten minutes without a connection. macOS starts PRIMA Bot again a minute later, and it reconnects once the internet returns. PRIMA Bot recovers without your help.

Getting Help

Getting Help explains how to report a problem. Include the last 20 lines of the log and the output of claude --version.