AgentCollision AgentCollision Docs

Troubleshooting

Start with agc doctor. It runs a battery of checks and usually diagnoses the problem with a one-line fix.

The hook isn't firing when Claude Code edits a file

This is the most common issue. Check in order:

Is the daemon running?

agc status

If not, start it:

agc daemon start

Is the hook installed?

agc install-hooks

This is idempotent. It detects which AI tools you have installed and wires up each one.

Did you restart your AI tool after installing?

Claude Code reads its settings at launch. After agc install-hooks, quit Claude Code completely (not just close the window) and relaunch. Same for Cursor, Cline, Windsurf, Codex CLI, and Gemini CLI.

Is this a git repo?

As of v0.11.6, AgentCollision protects every git repo on your machine automatically — no per-repo setup. If git rev-parse --show-toplevel succeeds in the directory, leasing is on. If it isn't a git repo, file edits there fail-open (no protection, but nothing breaks).

To opt a specific repo OUT, run agc disable from inside it. agc enable turns it back on.

A lease is stuck in "held" and won't release

Usually means the holder crashed. Wait for the lease TTL (default 30 minutes) and it releases automatically.

If you need to release it sooner, enable allow_revoke in your local settings (localhost:7777/ui/settings → Allow lease revoke), then use the Release button on the Leases page.

Be careful with revoke. If the holder is still running and just in the middle of a slow tool call, revoking the lease will make its next edit collide with whatever grabs the lease next. Only revoke when you're sure the holder is dead.

The daemon won't start

Port already in use

Default port is 7777. If something else is using it, pick another:

agc daemon start --port 7780

Or change it permanently in settings.

Socket file stale

If the daemon was killed ungracefully, the Unix socket may be stale:

rm ~/.agentcollision/daemon.sock
agc daemon start

Database locked

If another daemon is running, stop it first:

agc daemon stop
# wait 2 seconds
agc daemon start

All else fails

agc doctor

How to upgrade — and what to do if the upgrade didn't take effect

The 1-line upgrade

agc self-update

That swaps the binary and restarts the daemon on the new version. agc version should report the new number. Done.

Alternatively, if you installed via Homebrew: brew upgrade agentcollision (post-install handles the daemon restart automatically).

If the daemon is still running the old version after upgrade

Most often agc self-update handles this. If agc version shows the new version but agc status still reports an old daemon, run:

agc heal

This kills the old daemon, re-bootstraps launchd, and verifies the new version is up.

If agc heal reports "launchd domain stuck"

Rare, only on macOS, only on long-lived installs. macOS launchd has a phantom registration that bootstrap can't clear without a session reset. The fix is one of:

Until you do this, the daemon is still running the new version (self-update spawned it directly), but won't auto-restart on next login. Doing the logout once permanently fixes it.

Team sync isn't working

Check team status

agc team status

You should see:

Coordinator unreachable

Your daemon falls back to local-only mode when the coordinator is down. Check:

curl https://agentcollision-coordinator.agentcollision.workers.dev/healthz

Should return ok. If not, Cloudflare or the coordinator Worker is having issues — check status page.

Token expired or revoked

If an admin removed you from the team, your daemon will get 401 errors on sync. Re-authenticate with agc login:

agc team leave
agc login

agc login opens your browser to approve this machine again (assumes you're still on the team). If you've been removed entirely, ask an admin to re-invite you first.

The hosted dashboard can't connect

"Authentication failed"

Your team token is invalid or expired. Easiest fix: from any machine in the team, run agc team dashboard. It'll open the dashboard with fresh credentials.

"Coordinator unreachable"

CORS or network issue. Try:

File paths show as hashes instead of real names

Decryption isn't enabled. The hosted dashboard never receives your file paths in plaintext — the daemon HMAC-hashes them before sending. To see the real names, the dashboard needs your team's HMAC key.

Easiest: Settings → File Path Decryption → Import from local daemon. The button fetches the key from your machine's daemon over loopback (the key never leaves your machine). Requires the daemon to be running and v0.12.0 or later.

Manual fallback: paste the value of hmac_key_b64 from ~/.agentcollision/team.toml into the input on the same panel.

I have multiple AgentCollision accounts and the dashboard always says "Almost there"

Each daemon binds to one team at a time. If the dashboard you're looking at belongs to a team that isn't the one your daemon is currently bound to, the dashboard sees no machine and shows the "Almost there — install AgentCollision on your laptop" prompt, even though you already have it installed.

Check what teams this laptop knows about and which one is active:

agc team ls

The active team is marked with a *. Switch to the team that matches the dashboard you're viewing:

agc team switch <name>

Or click Switch this laptop to this team on the dashboard's "Almost there" panel — same result, one click.

I want to dismiss the install banner permanently

Click the × in the corner of the banner. As of v0.14.0 the dismissal is persistent per-team — it won't come back on the next page load. To bring it back, go to Settings → Display preferences and re-enable Show install banner.

"agc team switch: daemon not reachable"

The CLI talks to the daemon over its local socket. If the daemon isn't running, agc team switch can't apply the change. Start it:

agc daemon

Or check what's going on:

agc status

Once the daemon is up, retry the switch.

Clean uninstall

Remove hooks, binary, and all local state:

agc uninstall-hooks     # removes hooks from all AI tools
brew uninstall agentcollision  # or your install method
rm -rf ~/.agentcollision  # local state (leases, config)

On the team tier, also ask the admin to remove you via the dashboard:

agc team members              # find your laptop_id
# admin runs: agc team remove laptop_yourid

Still stuck?

Email hello@agentcollision.com with: