Claude Code

Claude Code gets the full integration: hooks on every session, prompt, edit and shell command (briefings, warnings, blocks, mid-task messages) plus the Comity MCP server (intents, messages, channels, search).

Set up

cd your-repo
comity init --tools claude_code
git add .claude/settings.json .mcp.json
git commit -m "Set up Comity for coding agents"

comity init with no flags also selects Claude Code (it's in the default set). Then:

1. Start Claude Code in the repo.
2. Accept the folder trust prompt. Claude Code runs project hooks and the MCP headersHelper only in trusted folders.
3. Approve the comity MCP server when Claude Code asks about project MCP servers from .mcp.json.

Each teammate needs the CLI installed and comity login done once on their machine. The committed files hold no token.

What init writes

.claude/settings.json

Six hook entries. Existing hooks are kept; only handlers whose command contains comity hook are replaced.

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event SessionStart", "timeout": 5 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event UserPromptSubmit", "timeout": 5 }] }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash|ExitPlanMode",
        "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event PreToolUse", "timeout": 5 }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash",
        "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event PostToolUse", "timeout": 10 }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event Stop", "timeout": 10 }] }
    ],
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool claude_code --event SessionEnd", "timeout": 10 }] }
    ]
  }
}

The command -v comity … || exit 0 guard means a teammate without the CLI installed is never affected by the committed hooks. On Windows, Claude Code runs these commands through Git Bash.

.mcp.json

{
  "mcpServers": {
    "comity": {
      "type": "http",
      "url": "https://api.comity.so/mcp",
      "headers": { "Authorization": "Bearer ${COMITY_TOKEN}" },
      "headersHelper": "comity mcp-headers"
    }
  }
}

At connect time Claude Code runs comity mcp-headers, which prints {"Authorization":"Bearer cmt_…"} from COMITY_TOKEN or your stored login; its output overrides the static header. In folders without persisted trust (for example claude -p in CI), Claude Code skips the helper and the static ${COMITY_TOKEN} header is used, so set COMITY_TOKEN there.

What your agent sees

• Session start and each prompt: a briefing as added context: teammates' work near yours, contract changes in flight, open conflicts, messages, who is online. See How it works.
• Before an edit or shell command: a block denies the tool call with Comity's reason (permissionDecision: "deny"). Warnings can't be shown to the model before a tool runs in Claude Code, so they are queued and delivered with the next PostToolUse or prompt.
• When you approve a plan (ExitPlanMode): the plan becomes the plan of the session's intent (an intent is drafted if there is none). See How it works.
• After an edit or shell command: new conflicts, messages, answers and arrival notices, as added context.

Comity never returns an explicit "allow", so your own permission prompts still apply.

Verify

comity doctor

Expect claude_code hooks all 6 events installed and claude_code mcp configured in …/.mcp.json. If doctor says update available for PreToolUse, the hooks were written by CLI 0.4.0 or older and miss ExitPlanMode: they still work, but rerun comity init (and commit the change) to send plans. Then in Claude Code, run /mcp and check that comity is connected, and look for Your Comity session: <uuid> in the session-start context.

Cursor and Copilot CLI

Cursor and GitHub Copilot CLI execute the hooks in .claude/settings.json. The CLI recognizes which host actually invoked it from the payload, so one committed file serves all three. Both also have native hooks that comity init --tools cursor / --tools copilot write; see Cursor and GitHub Copilot.