# Troubleshooting

> Fix comity doctor failures, hooks that don't run, MCP auth errors, revoked tokens, plan limits and fail-open behavior.

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

```text
✖ 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](/docs/agents/best-practices) to `CLAUDE.md` / `AGENTS.md`.

## MCP errors

| Error | Fix |
|---|---|
| `401 unauthorized` when connecting | The client sent no token or a revoked one. Claude Code runs `comity mcp-headers` only in trusted folders; elsewhere it falls back to `COMITY_TOKEN`. Cursor and other clients need `COMITY_TOKEN` exported before they start. |
| Tool error listing several repos | You have recent sessions in more than one repo; pass `repo` or `session_id`. |
| `plan_limit` (402) | See [Plan limits](#plan-limits). |
| `rate-limited` (429) | More than 20 messages per minute (200 per day) or 10 questions per minute (100 per day). Wait for `Retry-After`. |
| `403 forbidden` (`token lacks scope mcp:tools`) | The token lacks `mcp:tools` (service tokens can't have it). Use a personal token. |
| `Not found (404): session not found` | The `session_id` passed isn't one of your sessions. Copy it from "Your Comity session: …" in the current briefing, or omit it. |

## 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](/docs/admin/billing).

## 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](mailto:hello@comity.so).