Troubleshooting

#Connecting your first agent fails

What the install command printed tells you what's wrong:

• curl: (22) The requested URL returned error: 404 (or another curl: error) — the address in the command is wrong, or Agentower can't be reached from this computer. Copy the command again with the panel's Copy button rather than typing it, and check you're online.
• "Agentower refused the key" — the key was revoked or didn't copy fully. Create a new key in Keys & connections and copy the command again.
• "Couldn't reach …" — check your internet connection (and any company VPN or proxy), then run it again.
• A long script scrolls past and nothing is installed — only the first half of the command ran. The whole command ends with | sh -s -- at_… (your key); copy it again in one piece.
• "Paste your Agentower key" — the key wasn't part of the command. Paste it (it stays hidden) and press Enter, or copy the full command again.
• command not found: claude when you start an agent — Claude Code isn't installed on this computer yet. Install it first with Anthropic's instructions, then run claude again.

If the command finished with "Connected to Agentower." but no card appears, see below.

#An agent doesn't appear

Work down this list; most problems are the first two.

1. Start a new session. Hooks load when a session starts, so a session that was already open before you connected won't report.
2. Check the settings file. ~/.agentower/claude-code.env must have both AGENTOWER_URL and AGENTOWER_TOKEN, with no quotes or spaces around the values. The hook quietly does nothing if either is missing, or if the address starts with http:// (only https:// is allowed, except for localhost). While this file exists, AGENTOWER_URL and AGENTOWER_TOKEN set in the environment are ignored: put them in the file.
3. Check the key. On Keys & connections, your key should say "last used" a few minutes after a session starts. If it says "not used yet", the hook isn't reaching Agentower. If the key was revoked, create a new one and update the settings file.
4. Send a test event by hand — see below.
5. Check the hook entries. In ~/.claude/settings.json (or ~/.codex/hooks.json, ~/.cursor/hooks.json) the commands must point at $HOME/.agentower/agentower-hook.sh, and that file must exist.
6. On Windows, Git for Windows must be installed: the tools run hooks with its Git Bash.
7. Cursor: restart Cursor after changing hooks.json.
8. Codex: approve the new hooks when Codex asks you to review them.

#Send a test event by hand

This sends a test event with your settings and shows Agentower's answer:

. ~/.agentower/claude-code.env
curl -sS -X POST "$AGENTOWER_URL/v1/events" \
  -H "authorization: Bearer $AGENTOWER_TOKEN" -H "content-type: application/json" \
  -d '{"tool":"test","session_id":"hello-1","project":"connection-test","event":"start"}'

{"ok":true,"accepted":1} means the connection works, and a card appears under connection-test (it closes by itself after 30 minutes). {"error":"unauthorized"} means the key is wrong or revoked.

#Check a computer's connection

Settings → Computers → Check connection shows, for one computer, what Agentower has heard from it:

Send test checks the whole round trip without touching any agent: Agentower holds a test for that computer, the hook picks it up on its next settings fetch (about once a minute while an agent works there) and answers with just the test's id. The line then shows the round-trip time. "Not answered within 2 minutes" usually means one of:

• No agent is working on that computer right now — the hook only runs while Claude Code does something. Start or prompt an agent there and test again.
• The hook there is out of date (from before connection tests) or isn't installed.
• The computer is asleep or offline.
• Its key was revoked, or the address in ~/.agentower/claude-code.env is wrong.

#"Mac 1 stopped reporting"

The board shows a quiet line — "Mac 1 stopped reporting 22 min ago · Check connection" — when a computer with open agents has sent nothing (no hook event, status-line heartbeat or telemetry) for 20 minutes. It appears only for computers that would normally keep reporting: ones with the status line, or with an agent working. The usual causes: the computer went to sleep, lost its network, or Claude Code was closed without ending its sessions (they close by themselves later). Open Check connection to see which part stopped. You see this line only for your own computers (owners: everyone's). It isn't sent as a notification.

#An agent shows in the wrong state

• Idle, not Needs you, after a question. The hook decides from the last paragraph of the agent's reply: if it contains a "?", the agent shows as Needs you ("Asked you a question"). Otherwise it's Idle — its turn is finished.
• Cursor never shows Needs you. Cursor doesn't tell hooks when it's waiting for permission. See Connect Cursor.
• Still Working after the terminal was closed. Agentower closes a session it hasn't heard from after 30 minutes of working, 4 hours idle or 12 hours waiting. See When an agent closes by itself.

#The board says "Reconnecting…"

The board keeps a live connection to Agentower. Reconnecting… means it has dropped — usually a sleeping laptop, a change of network or a flaky connection. The board notices a dropped connection within about half a minute (it checks every 20 seconds), checks again as soon as you come back to the tab or your network returns, and reconnects by itself — retrying after half a second, then 1, 2, 4 and at most every 8 seconds. If it can't, it falls back to checking every 5 seconds (the pill's tooltip says so) — the board still updates.

If it stays on Reconnecting:

• check you're online, then reload the page;
• a company proxy or VPN that blocks WebSockets can stop the live connection — checking every few seconds still works;
• if you've been removed from the team, or your sign-in has expired, sign in again.

#"Agentower has reached today's free usage limit or can't be reached right now"

The board shows this when Agentower can't take updates for a while. Your agents keep working — nothing waits on Agentower — and the hook keeps what it couldn't send and sends it later, so the board catches up automatically (hook version 13 or plugin 0.4.7; older hooks drop those updates). Nothing to do.

#Signed out unexpectedly

You're signed out after 24 hours with no activity in Agentower, and after 30 days in any case; the sign-in page then says "You were signed out after a period of inactivity." An owner can change the idle time for the workspace in Settings → Workspace → Sign out when idle (1 hour, 8 hours, 24 hours or 7 days; owners only, with a sign-in from the last 7 days, and recorded in the audit log). If you're in several workspaces, the shortest applies. Answering agents and payments still need a sign-in from the last 7 days.

#Agents go into Unsorted

An agent goes into Unsorted when its session was started in a folder that isn't a project: your home folder, or a folder that holds two or more repositories (such as ~/Projects). Start Claude Code inside the project's folder instead (cd ~/Projects/billing-api && claude).

If you have other folders like that, list them in AGENTOWER_UNSORTED_DIRS in ~/.agentower/claude-code.env (separated by :) so they're treated the same way.

The project name comes from the repository's origin remote when there is one, so two clones of the same repository share a project.

#Plan limits are empty

• The Agentower status line isn't set up — it isn't part of the hook. See Plan limits.
• For Codex: limits arrive at the end of a Codex turn, through the hook — check Codex is connected.
• You already had a status line of your own, so the Agentower one wasn't used.
• Claude Code is signed in with an API key: API-key logins have no plan limits.
• No session has run since you set it up — the card fills in after Claude's first reply.

#No tokens or cost

Tokens and cost come from the tool's own telemetry. The one-line installer switches it on for Claude Code; run it again without --no-usage if you turned it off, and restart Claude Code sessions afterwards (each reads its settings when it starts). If Claude Code already sends its telemetry to your own monitoring, the installer leaves it alone — send it to both, or add the env block in Connect Claude Code; for Codex, the [otel] section in Connect Codex. Cursor doesn't send usage.

#Allow/Deny or messages don't reach my agent

If the chat says "Answers from Agentower are off on this computer.", or Allow, Deny and the message box are missing on an agent that otherwise looks fine, check the agent's computer:

• If it says "Answers from Agentower are switched off for Mac 1", the computer allows answers but they're switched off in the app: its person can press Turn on answers for Mac 1 in the chat, or use the switch in Settings → Computers. An owner can switch a computer off, but only its own person can switch it back on.
• If it says "Confirm once on this computer:", the computer itself doesn't allow answers: run the command shown, on that computer.

• AGENTOWER_REMOTE in ~/.agentower/claude-code.env must be own or team. It's off if the line is missing, so computers set up before this setting existed are off until you add it. Setting it in the environment doesn't help while that file exists: the file's address, key and AGENTOWER_REMOTE win over the environment — see Answers from Agentower on this computer.
• With the Agentower plugin, its Answers from Agentower on this computer option (remote_answers) is used instead of the file.
• If it says "Only Maya can answer this agent.", that computer is set to own: only the person running the agent can answer it. They can change it to team.
• Through the API, the same cases come back as 409 remote_off and 403 remote_not_allowed.

#Allow shows as "Approve this in the terminal"

Agentower shows Deny only when it can't show everything allowing would let through — the detail was cut to fit, it had invisible characters, the tool's input isn't shown at all (MCP tools, Task), or it's a file change (Write, Edit, MultiEdit, NotebookEdit), where Agentower shows only the file's path, not what would be written. For a plan, it shows Keep planning only when the plan is over 12,000 characters or had characters Agentower had to remove. Approve it in the agent's terminal. See Allow or deny a permission request.

#Allow and Deny don't show

• Agent chats must be on for the workspace (an owner switches it in Settings → Workspace) — see Switch on Agent chats.
• The agent's computer must allow answers from Agentower — see above.
• You need to be an owner, or an approver for that project.
• The agent must be Claude Code or Codex.
• perl must be available on the agent's computer (it is on macOS, most Linux and Git for Windows).
• Answering needs a sign-in from the last 7 days: sign out and in again if yours is older.
• If a banner says the Team plan for this workspace ended, only the person who created the workspace can answer until Team is renewed — see When a Team plan ends.

#"Couldn't create the key"

A workspace can have up to 20 active keys, counting everyone's, and people who aren't owners can hold at most 5 of their own. Revoke keys you no longer use on Keys & connections.

#"Notify me" does nothing

Browser notifications only appear while you're looking at another tab or app — if Agentower is in front of you, nothing pops up. Switch on Chime or Speak it in Settings → You to hear it even then. On a Mac, also check System Settings → Notifications → your browser → Allow notifications. Send a test checks all of it.

#A notification didn't arrive

Open Settings → Notifications: the channel's row shows its last error. Press Send test. If the service answers 404 or 410, the webhook was removed on the service's side — remove the channel and add it again with a new address. Needs-you notices with a delay aren't sent if the agent was answered in the meantime.

#The sign-in link doesn't arrive

Check your spam folder, and that the address is right: for safety, the sign-in page says the same thing whether or not the email could be sent, so it can't tell you the email failed. Links work for 15 minutes; ask for a new one if yours is older.

Email sign-in also has a daily limit for everyone together. When it's reached, the form says sign-in by email is busy: use Continue with Google, or try again tomorrow (it resets at 00:00 UTC).

#Signed in on a computer you no longer use

Go to Settings → You and press Sign out everywhere. It ends every session of yours — on all browsers and devices, this one included — and boards left open elsewhere stop receiving updates straight away (their live connection is closed, not just left to time out). Then sign in again here. When you sign in from an email link, the page shows which address it signs you in as, so you can spot a link someone else sent you.

#Still stuck?

Email hello@agentower.com with what you tried. Please don't send your key.