Troubleshooting

Each problem below starts with its cause, then the fix. If yours is not here, see Getting help at the end.

Why don't requests reach the HUD?Copy Anchor Link

Requests reach the HUD through hooks in each agent's own settings, and Agent HUD writes them only when you ask.

1. Client hooks are off. They are off until you turn them on: Settings → General → Clients → Client hooks.
2. Agent HUD is not in Applications. Only the Agent HUD at /Applications/Agent HUD.app can install client hooks. Opened from anywhere else, the switch stays unavailable. Move the app to Applications and open it from there.
3. Agent HUD is not running. Each agent then asks in its own window, as usual.
4. The agent does not send requests. Only some agents do, and some need more: Codex needs its hook trusted (next question), DeepSeek Harness needs Agent HUD's plugin from Settings → Agent plugins. See Client hooks.

A request you leave goes back to the agent after Wait for an answer, 10 minutes unless you change it.

Why did Codex stop sending requests to the HUD?Copy Anchor Link

Codex runs a hook only after you trust it, and it stops running a hook whose command has changed until you review it again, without telling you. Agent HUD adds or changes Codex's hooks when you turn on client hooks and when you turn on Remote sessions.

• Fix: review Agent HUD's hooks in Codex and trust them again.
• Also check: Codex hands Agent HUD only the requests you review yourself. Requests its automatic reviewer handles stay in Codex.

Why did an agent's quota disappear from the panel?Copy Anchor Link

Agent HUD reads a quota with the agent's own sign-in. When the agent's command line is signed out, there is no account to read, and the quota block leaves the panel. Sessions and tokens stay.

• Claude Code: run claude in Terminal and sign in again. The quota returns at the next read. The Claude desktop app keeps working meanwhile, because it signs in on its own. When a read fails only for a moment, the last reading stays and Agent HUD tries again by itself.
• Signed in with an API key or a third-party platform: such a login has no plan limits, so there is no quota to show.
• GitHub Copilot CLI: its quota appears only after you turn on Read GitHub Copilot quota in Settings → Agents.

Why can't my iPhone find my Mac?Copy Anchor Link

On the same network, the iPhone reads the Mac directly, and only after you pair them.

1. Sharing is off. On the Mac, turn on Settings → Local Network → Local network sharing. It is off until you turn it on.
2. The invitation expired. An invitation works once and expires after five minutes. Click Create invitation again and scan the new code.
3. The devices are on different networks. Put the iPhone and the Mac on the same Wi-Fi network. Away from it, the iPhone needs Agent HUD Remote.
4. iOS blocks the connection. Allow local network access for Agent HUD in the iPhone's Settings → Privacy & Security → Local Network.
5. The pairing was revoked. After Revoke paired devices on the Mac, the iPhone asks you to scan the Mac's code again.
6. One app is too old. When the iPhone asks you to update Agent HUD on both devices, update both.

Agent HUD must be running on the Mac for the iPhone to read it.

Why isn't Remote updating?Copy Anchor Link

Remote passes everything through your iCloud. The Mac sends usage and sessions about every 30 seconds, and requests and alerts at once.

1. Different Apple Accounts. The Mac and the iPhone must be signed in to the same Apple Account.
2. Remote is off on the Mac. Turn on Settings → Remote → Agent HUD Remote.
3. The Mac has no seat. In Settings → Subscription, the Agent HUD Remote row should name the App Store. If it reads "Not active on this computer", click Use an App Store seat. When every seat is in use, remove another Mac first.
4. Agent HUD is not running on the Mac, or the Mac is asleep. Nothing is sent until it runs again.
5. Your iCloud storage is full. iCloud refuses new records; the Mac tries again every hour. Free up iCloud storage.
6. The subscription ended. The iPhone shows Agent HUD Remote has expired and the last data it received.

The Mac's Settings → Remote shows the iCloud connection under Status, with the saves still waiting and when it last saved. On the iPhone, pull down on Home, Stats or Sessions to read iCloud again.

Requests, conversations and messages need more than syncing: Remote sessions and Share conversation on, client hooks on, and Agent HUD's plugin for Claude Code. See What the Mac needs.

Why do the numbers look wrong?Copy Anchor Link

Most surprises come from what a number counts.

• Cost is an estimate, at each vendor's list price, marked ≈. It is not a charge. If a model's price is wrong, set your own in Settings → Prices.
• Token history stays 30 days on your Mac. Older tokens are gone.
• Sub-agents count inside the session that started them, so a session's tokens include its sub-agents' work.
• Quota belongs to the account. Two Macs on the same account read the same windows; the iPhone shows the account once, with the newest reading. Token history, by contrast, stays with the Mac that did the work.
• Cursor's usage comes from your Cursor account, so it includes work done on other computers.
• A grey quota has a reading that is not normal, or a reset time that has passed. It stays grey until the next reading.
• On iPhone and Apple Watch, a percentage is always the share used.

Why doesn't a message reach another agent?Copy Anchor Link

Agent messages need Let agents message each other on, a new session in the sending agent, and a way into the receiving session. The reasons the sender is given, and what to do about each, are in Agents messaging each other.

How do I get help?Copy Anchor Link

• Report a problem or ask a question in GitHub issues. Say which Agent HUD and macOS versions you run, which agent is involved, and what you expected to see.
• Write to support@agenthud.app for anything about your subscription, or anything you would rather not post in public.