Troubleshooting

Start with comity doctor in the repo where your agent runs. It prints a › hint under every warning and failure; this page explains each one.

comity doctor checks

config: not logged in

✖ config             not logged in (…/comity/config.json missing and COMITY_SERVER/COMITY_TOKEN unset)

Run comity login. On a headless machine, comity login --token cmt_… or set COMITY_SERVER and COMITY_TOKEN.

server: unreachable or slow

• unreachable: check the network, VPN or proxy, and the server URL (COMITY_SERVER, or comity login --server <url>).
• reachable in N ms (above the 400 ms hook budget): before-edit checks that take longer than 400 ms are skipped (the edit proceeds without coordination). Try another network; a VPN often adds the latency.

token: rejected by server (401)

The token was revoked (on the Team tab, or because you were removed from the org), expired, or belongs to a different server. Run comity login again. If COMITY_TOKEN is set in your shell, it overrides the stored login: update or unset it.

token: missing scopes hooks:evaluate, mcp:tools

The token wasn't created by comity login (for example a service token or a custom-scoped one). Run comity login for a personal token with every CLI scope.

git: not inside a git repository / has no remotes

Hooks only coordinate git repositories with at least one remote, because the remote identifies the repo across machines. Run the agent inside the repo, or add a remote: git remote add origin <url>.

claude_code hooks / codex hooks: not installed or missing events

Run comity init --tools claude_code (or codex) in the repo, then commit the files. If you edited the hook files by hand, re-running init restores Comity's entries without touching yours.

claude_code mcp / codex mcp: authenticates with COMITY_TOKEN, which is unset

The MCP entry was written by an older CLI or by hand and relies on COMITY_TOKEN. Re-run comity init --tools <tool> to use comity mcp-headers, or set COMITY_TOKEN.

omp extension: from another CLI version / not the Comity bridge

Re-run comity init --tools omp after updating the CLI; it rewrites .omp/extensions/comity/index.ts.

round trip: session_start failed

The server is reachable and the token valid, but the hook endpoint failed. The detail shows why. Until it works, agents run without coordination (fail-open).

CLI up to date: newer version available

Run comity update.

Hooks don't seem to run

1. Codex: open /hooks in Codex and approve the comity hooks. Codex skips unapproved project hooks, and comity doctor can't see the approval.
2. Claude Code: accept the folder trust prompt. Untrusted folders don't run project hooks.
3. Cursor: turn on Include Third-Party Plugins, Skills, and Other Configs (Cursor Settings → Agents → Third-Party Imports) and check the Hooks output channel.
4. The CLI isn't on the agent's PATH: the committed hooks exit silently when comity isn't found. Run command -v comity (or where comity on Windows) in the environment the agent starts from.
5. Not logged in on this machine: hooks skip silently without a server and token.
6. Look at hook.log in the CLI config folder (~/.config/comity/hook.log, or %APPDATA%\comity\hook.log on Windows). Every hook that failed open writes one line with the host, event, session and error.

Your session should appear in the dashboard under Activity within seconds of starting the agent.

The agent never mentions Comity

Ask it: "What did the Comity briefing at session start say?" If it has none, the SessionStart hook didn't run (see above). If it has the briefing but doesn't use the MCP tools, check the MCP connection (/mcp in Claude Code or Codex) and add the agent instructions to CLAUDE.md / AGENTS.md.

MCP errors

Token revoked or member removed

A revoked token fails everywhere at once: hooks skip silently (fail-open), MCP returns 401, comity status shows token rejected by server. Run comity login on that machine. A removed member's tokens are revoked for that org.

Plan limits

On the Free plan, the first 5 developers active in a month are coordinated; others aren't, until the next month or an upgrade:

• their agents get one notice per session ("Comity plan limit: …") and then run uncoordinated (hooks allow everything),
• their MCP tools return plan_limit,
• comity status shows over limit and who isn't coordinated.

A 4th repository on Free isn't registered: hooks in it allow with a notice. An owner can upgrade in Settings → Plan & usage; caps lift immediately. See Billing & plans.

Fail-open behavior

Comity never stops an agent because Comity itself has a problem. When the API is unreachable, slower than 400 ms before an edit (1.5 s for other events), or returns an error, the hook prints nothing and the agent proceeds as if Comity weren't installed, and one line goes to hook.log. Blocks only happen when the API answers with a block under your policy. If you expected a block and didn't get one, check hook.log and the server latency in comity doctor.

Windows

• Claude Code runs hook commands through Git Bash; install Git for Windows.
• Codex runs them through Windows PowerShell; comity init writes a commandWindows variant that finds comity.cmd and works under the default execution policy.
• comity update failing with EBUSY/EPERM: close other terminals and agent sessions using comity, then run the printed npm install -g … command.

Still stuck

Run comity doctor --json and comity status --json, include the last lines of hook.log, and email hello@comity.so.