Something's wrong

bighelp can't reach your computer, or keeps saying Reconnecting…

1. Check that the computer is on and awake, and that Hermes is running on it.
2. Check that your phone can reach the computer. At home, use the same Wi-Fi. Away from home, turn on Tailscale or your VPN on the phone. If you see "Can't reach this computer over Tailscale. Turn on Tailscale on this device, then try again.", that's the fix.
3. Check the address. Open Settings › System, tap your computer under Computers, then Address and access.
4. On the screen that says it's connecting, tap Reconnect.
5. Still stuck? Restart Hermes on your computer, then try again.

Why: bighelp talks straight to Hermes on your computer. There's no bighelp server in between, so your phone has to reach the computer itself. When the connection drops, bighelp tries again by itself, and your computer's row in Settings › System says In use · Reconnecting…. A pill at the top of the screen says Not connected or No internet only when it really can't connect.

An error when you add your computer

Find the message, then do what the right column says.

hermes config set dashboard.public_url https://hermes.example.com

Why: bighelp checks the address before it signs in, and says which part stopped it. There's more on addresses in Connect your computer.

It asks you to sign in again

1. Open Settings › System and tap your computer under Computers.
2. Tap Sign in again and use your Hermes login, the same one as Hermes' dashboard.
3. If it says "The host is limiting sign-in attempts. Wait before trying again.", wait a few minutes first.

Why: Hermes ends sign-ins after a while, or when its login changes. You see "Your host session has expired. Sign in again." or "The host rejected these credentials. …". bighelp keeps your login in the Keychain on this device only.

How to restart Hermes on your computer

Several fixes say to restart Hermes. Restart both parts: the dashboard (the part bighelp connects to) and the messaging gateway.

1. If you use the Hermes Desktop app, quit it and open it again. That's all.
2. Otherwise, restart the messaging gateway in a terminal:

   hermes gateway restart

3. Then stop the dashboard:

   hermes dashboard --stop

   Start it again the same way you started it before (the same command, with the same --host and --port, or the login item or service that starts it).

You can restart the messaging gateway from the app too: Settings › System › Restart Hermes Gateway.

The app asks you to update the plugin

For example: "Your Hermes host is running an older bighelp plugin", or "Update the bighelp plugin on your computer to …".

1. Open Settings › System. In the bighelp plugin section, tap Update Plugin.
2. When the app offers it, tap Restart Hermes. Replies in progress on your computer stop, and bighelp reconnects.
3. Go back and try the feature again.

Or update on the computer, then restart the dashboard:

hermes bighelp update --restart

Already updated and still see it? Restart Hermes on every computer this phone connects to, so each one loads the new copy.

Some messages say "under this computer's Plugin version". That's the bighelp plugin section in Settings › System. For another computer, tap it under Computers first.

Why: Many features come from the plugin on your computer, not from the app. bighelp asks the plugin what it can do and offers the update when a feature is missing. It never checks version numbers. --restart restarts the gateway once, and the dashboard keeps the old copy until it restarts too.

A plugin update says to restart Hermes on your computer

The message says the new version is installed, but Hermes still runs the old one, and to restart it on your computer once, then tap Check for Updates.

1. Restart Hermes on your computer, the dashboard and the gateway.
2. In bighelp, open Settings › System and tap Check for Updates in the bighelp plugin section. It should say Up to date.

Why: Plugins older than 2.17.0 can't restart Hermes by themselves. After this one restart by hand, later updates restart from the app.

hermes bighelp update stops or refuses

1. See what happened:

   hermes bighelp update-status

2. If it says the update was superseded, another install (for example from the app) replaced it first. Run hermes bighelp update again if you still need it.
3. If you changed files in the plugin's folder, or installed it from a folder on your computer, the updater leaves it alone. Update from the app instead: Settings › System › Update Plugin.
4. If it waits and then times out, restart the dashboard and check update-status again.

Why: The updater installs only a newer GitHub release, backs up your copy first, and never overwrites a changed install. It needs launchd on macOS or user systemd on Linux. An update counts as done only when the restarted Hermes runs the new release, and it waits up to 5 minutes for that.

A chat says it's open in another Hermes window or process

You might see "This chat is open in another Hermes process, so bighelp is continuing it in a new chat with the same history. Your text has been kept." or "Hermes is at its limit of open chats. Finish a chat in another Hermes window, then try again."

1. Usually there's nothing to do. bighelp goes on in a new chat with the same history. You'll see "This chat went on in a new chat with the same history. Find it in Sessions."
2. If it says it couldn't continue, start a new chat. Your text is kept.
3. For the limit of open chats, finish a chat in another Hermes window, such as Hermes Desktop or a terminal, then send again.
4. If it shows up after every plugin update, update and restart from the app (Settings › System, Update Plugin, then Restart Hermes). That restart clears chats left marked as open.

Why: Hermes lets one process work on a chat at a time. After some restarts, old chats can look busy for a while. The plugin's own restart clears them.

Approvals or questions never show up on your phone

1. Update bighelp and the plugin.
2. Close the chat and open it again. Each time bighelp connects, it tells Hermes it can show approvals and questions.
3. If you connect through a proxy or tunnel, try the address on your home network. If prompts show up there, the proxy is changing or dropping messages. Let it pass connections through unchanged.
4. Check the agent's approvals setting. If approvals are off, the agent doesn't ask. In Bots mode it's Approvals in Settings.

Why: Hermes only waits for your answer when the app has said it can show prompts. If that message never reaches Hermes, Hermes goes on without asking you.

A message is stuck on Sending…

1. Keep bighelp open. It sends the message as soon as the chat can take it.
2. Check the connection. If the pill at the top says Not connected, see Can't reach your computer.
3. After about 25 seconds with the app open, bighelp puts your text back: "Your computer didn't answer, so your message is back in the message box." Send it again once you're connected.
4. Don't close bighelp while a message says Sending…. Waiting messages aren't saved, so closing the app loses them. Copy the text first if you have to.

Why: With no connection, or when the chat isn't ready for a new message yet, bighelp holds your message and sends it in order. Time in the background doesn't count toward the 25 seconds.

It says "Message delivery is unconfirmed"

The full message is "Message delivery is unconfirmed. It will not be sent again automatically."

1. Wait a moment and watch the chat. If the agent answers it, it got your message.
2. If nothing happens, send the message again yourself.

Why: The connection dropped before Hermes confirmed it had your message. bighelp never sends a message twice on its own, so it tells you instead.

Steer isn't offered on a chat that was already running

1. Wait until you see the agent's live reply in the chat. Then hold Send for 1 second and pick Steer.
2. Or pick Queued to send it when the agent finishes, or Interrupt and Send to stop the agent and start on your message.
3. If you see "Hermes could not steer this turn. Your message is still available to edit or queue.", send it as Queued.

Why: bighelp can only steer a reply it is watching live. When you open a chat that was already working, for example one started on another device, bighelp waits until it sees the live reply itself.

The chat list looks out of date after you come back

1. Wait a few seconds. The list updates in one go once bighelp has caught up.
2. If a list didn't load, tap Retry.
3. If nothing changes, check the connection.

Why: This is on purpose. While bighelp catches up on what happened, it keeps showing the list you last saw, then updates it all at once so rows don't jump around.

A card didn't show, or says "Invalid or unsupported card"

1. Update bighelp. A card type that's newer than your app shows as Invalid or unsupported card.
2. Ask the agent to send the card again, in its reply.
3. "This card couldn't be shown." means the card was broken or too big. Ask the agent to make it again, simpler.
4. Update the plugin.

Why: Making a card isn't enough. The agent has to put the card into its reply, once. And bighelp only draws the kinds of cards it knows.

Your agent says a phone tool is unavailable

1. Keep the agent's chat open on your phone, unlocked, while it works.
2. Open Settings › Connections › Device access and turn the tool on. If iOS said no, tap Allow access in iOS Settings.
3. Read the note on the Device access page and do what it says. For example:
   • "Open a chat to use this iPhone’s shared data."
   • "Another device uses this chat’s shared data. Close the chat there, then open it again here."
   • "Device access is not connected. Check the bighelp plugin on this host, then reopen the chat."
4. Update the plugin.
5. If only one agent never gets phone tools, check in Hermes that the bighelp plugin is on for that agent.

Why: Each phone tool is off until you turn it on, and it works only while you have a chat with that computer open, or for a short time after you leave. So an agent can't use your phone when you aren't there.

Phone tools stop when bighelp is in the background

1. Stay in the agent's chat until it's done with the phone step.
2. For a long job, ask the agent to do the phone steps first.
3. If a tool stopped partway, open the chat again and ask the agent to go on. bighelp connects the tools again by itself.

Why: bighelp keeps phone tools open for about 25 seconds after you leave the app. A shortcut that the agent runs gets up to 60 seconds. After that, the tools pause until you come back.

The agent isn't sure if an action happened

1. Look for yourself in the app it used: Calendar, Reminders, Contacts, Photos or Shortcuts.
2. Tell the agent what you found. If it isn't there, ask the agent to do it again.
3. Don't ask it to repeat the action before you check, or you might get two.

Why: If the connection dropped while your phone was changing something, bighelp can't know if the change finished. It never runs an unfinished change twice, and it tells the agent not to repeat it.

A contact or event needs review

The card says Contact draft or Event draft, with "Ready for you to review. Nothing is saved yet." or a count like "1 thing to check".

1. Tap Review.
2. Check the details next to the photo and fix anything wrong.
3. Tap Save to Contacts or Add to Calendar. Or tap Discard to save nothing.
4. If it says "It's not clear the contact saved. Check Contacts before you try again.", tap Look in Contacts, then It's in Contacts or It's not there. Events work the same way with Calendar.

Why: When a chat has a photo, the agent has to show you a draft first. A misread business card or poster never goes straight into your contacts or calendar.

No notifications after you turned them on

1. Open Settings › Notifications. If setup stopped, you see a message and a code, like Code NS-102. Look up the code.
2. Under iOS notifications, check that Notifications says Allowed. If it says Denied, tap Open System Settings and turn on Allow Notifications for bighelp.
3. Check Quiet Hours and your Focus. In Quiet Hours, your computers send no notifications.
4. Check Notify Me About. Turn on the kinds of alerts you want.
5. If you see Send Test Notification, tap it. You should see "Test sent. Check your notifications."
6. Still nothing? Tap Set Up Again. It clears this computer's notification setup, on the computer and on this device, and sets it up fresh.

Why: Your computer sends each alert, sealed for your phone, through bighelp's notification service. That needs the plugin on your computer, permission from iOS, and a finished setup between them.

Alerts stopped by themselves

1. Open bighelp. When it comes to the front, it checks each computer's notification setup (at most once an hour) and quietly sets up again any that the computer dropped.
2. No alerts after that? Open Settings › Notifications and tap Set Up Again.
3. If you see a code, look it up.

Why: A computer stops sending to your phone when the notification service says the phone's setup is unknown or retired, for example after a reinstall. bighelp repairs this itself the next time you open it, without a message.

Nothing arrived during Quiet Hours

1. Open the chat. Replies wait there.
2. To change the hours, open Settings › Notifications › Quiet Hours and set From and To, or turn Quiet Hours off.
3. If it says "Quiet Hours needs a plugin update on …", update the plugin on that computer.

Why: In Quiet Hours your computers send this device no notifications, and they don't send the skipped ones later. Live Activity updates go on.

You see a code like NS-102

1. Read the message above the code. It says what to do.
2. Find the code on Notification error codes for more detail.
3. To send it to us, tap Copy Details and paste it in a GitHub issue.

Voice won't start, or you hear nothing

1. Allow the microphone. If you see "Allow microphone access in Settings to start live voice." or "Microphone access is denied. You can allow it in iOS Settings.", open the Settings app, find bighelp, and turn on Microphone. For TTS, turn on Speech Recognition too.
2. Check the sound: the volume, the silent switch, and where audio goes (headphones, Bluetooth or the car). "Audio is unavailable. Check your audio route and try again." means bighelp can't use the current audio route.
3. Read the message and do what it says. For example:
   • "Another live voice call is still open with your computer. End it, then try again."
   • "Live voice isn't set up on your computer. Use TTS voice mode instead." Set Settings › Voice › Voice mode to TTS.
   • "Your computer couldn't turn that into text. …" Set Speech to text to This device in Settings › Voice.
   • "Codex sign-in on your computer didn't work. …" Sign in again on the computer:

     hermes auth add openai-codex

4. Close voice and open it again.
5. In a Gemini Live call with no sound, turn on Nerd Mode in Settings. Then open Settings › Voice and tap Restart sound under Debug.

Why: In TTS mode, your words become text and the agent's speech provider reads each reply. In Full Duplex, your computer starts a live call with a voice provider. Both need the microphone and a working provider on your computer. There's more in Voice.

Gemini voice is missing

1. Update the plugin. Older plugins don't offer Gemini Live. The app says "Update the bighelp plugin on your computer to talk with Gemini Live."
2. Open Settings › Voice. Set Voice mode to Full Duplex, then set Provider to Gemini Live, your Gemini key.
3. If it says "This agent has no Gemini API key on your computer. Add one as GEMINI_API_KEY, then try again.", add your key to that agent's settings file on the computer, then restart Hermes. For your main agent:

   echo 'GEMINI_API_KEY=paste-your-key-here' >> "$(hermes config env-path)"

   For another agent, put its name after -p:

   echo 'GEMINI_API_KEY=paste-your-key-here' >> "$(hermes -p NAME config env-path)"

Why: Gemini Live needs a newer plugin and that agent's own Gemini key on your computer. The key stays on the computer and never comes from your phone.

Composio apps are missing in an older chat

1. Start a new chat with the agent.
2. Open Settings › Connections › Composio Apps. It should say the agent can use these apps. If it offers Turn on for my agent, tap it.
3. If it asks you to update the plugin, do that first.

Why: A chat gets its tools when it starts. As the Composio page says, "A chat that was already open may not have them."

The Files tab says there's no working folder

You might see "This agent's chats start in a folder that isn't its own, …" or "This agent works in Hermes's own folder, which holds its settings and keys, so bighelp won't show it. …"

1. Make a folder named workspace in the agent's Hermes folder. For your main agent:

   mkdir -p ~/.hermes/workspace

   For another agent, use its name:

   mkdir -p ~/.hermes/profiles/NAME/workspace

   Or choose a working folder for the agent in Hermes.
2. Tap Try Again.

If you moved Hermes' folder, use that folder instead of ~/.hermes.

Why: bighelp never shows Hermes' own folders, because they hold the agent's settings and keys. It shows the agent's working folder instead.

A workflow stage says "We don't know how … ended"

1. Open the run. The stage shows Needs attention.
2. Look at what the stage did so far.
3. Tap Try again to start a new attempt. The old one stays on the record. Or tap Cancel run.

Why: Hermes or the computer restarted while the stage ran, so nobody knows if it finished. "Nothing tries again by itself", so no work runs twice without you.

Code mode sends start one at a time

That's normal. The card says "Sessions start one at a time, then run side by side." Each one shows Starting, then steps like "Making the worktree…" and "Sending your message…".

Why: Hermes starts one new chat per agent at a time, and each new worktree changes the project the next send reads. Once they've started, the sessions work side by side.

A sheet on Mac won't close

1. Press Esc.
2. Update bighelp: in the bighelp menu, choose Check for Updates….
3. Still stuck? Quit bighelp (⌘Q) and open it again.

Why: Older Mac versions of bighelp could leave a sheet on screen after it closed. Newer versions close it themselves.