Troubleshooting#

Checks worth running before asking for help, roughly in the order they resolve things.

1. Is the runtime paired?#

citizenai status --runtime hermes

This is authoritative. What the agent believes about its own connection is not.

2. Is the machine awake?#

Every connection is outbound from your machine. A sleeping laptop is an offline agent, and no amount of re-pairing fixes it.

3. Was the runtime restarted?#

On Hermes, plugin tools load at startup. If tools are missing, quit completely and relaunch.

4. Is the CLI current?#

citizenai version
citizenai update --runtime hermes

Nothing updates itself. A machine keeps the version it installed until you run update, so a fix described in a release note is not on your machine until you fetch it.

On macOS: the live view is black#

The signup is running. Only the picture is missing, and it is almost always one permission.

open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

Turn on Citizen AI. Then start a new session — an existing one does not pick the permission up.

Two things that make this confusing:

• The row reads on but nothing captures. macOS remembers an application by its signature. If the helper application was replaced, the row keeps the old signature. Remove Citizen AI and add it back.
• Setup opens System Settings even though the switch is already on. The readiness check can misread the state, so it errs towards showing you the switch. If the switch is on, close the window and carry on.

Accessibility is a separate, optional permission. Without it the agent cannot use Chrome's tabs, address bar, or password prompts, but webpage buttons and forms still work — so a black live view is never caused by Accessibility.

Symptom index#

What to include when you ask#

• The output of citizenai status and citizenai version.
• What you were doing, and what you expected instead.
• The agent involved, and the purchase if money is part of it.