Docs

Get started

Quickstart

Install the CLI, sign in, set up a repo, verify it, and watch Comity catch your first conflict.

On this page

You need Node.js 22 or newer, a git repository with a remote (for example on GitHub), and Claude Code or Codex. Allow about ten minutes.

1. Create your org

Sign up at comity.so/signup and create an org. The org's slug (e.g. acme) is how the CLI and API address it. If a teammate already uses Comity, accept their invite instead.

2. Install the CLI

Terminal
npm i -g https://api.comity.so/cli/comity-cli.tgz
comity --version

3. Sign in

Terminal
comity login

The CLI shows a code and opens your browser. Check that the code matches, pick the org, and click Approve. The CLI stores a token for this machine in your user config folder:

✔ Logged in as diego@acme.com · org acme · role owner

On a machine without a browser, comity login still works: open the printed URL on any device where you are signed in to Comity and enter the code.

4. Set up a repository

Terminal
cd ~/code/acme-api
comity init

In a terminal, init asks which agents to set up and pre-selects the ones it finds. It writes:

  • Claude Code: .claude/settings.json (hooks) and .mcp.json (MCP server)
  • Codex: .codex/hooks.json (hooks) and .codex/config.toml (MCP server)

No token is written. Commit the files so every teammate's agents are coordinated as soon as they pull and have run comity login:

Terminal
git add .claude/settings.json .mcp.json .codex/hooks.json .codex/config.toml
git commit -m "Set up Comity for coding agents"

5. Check the setup

Terminal
comity doctor
✔ config             server https://api.comity.so [file], token [file], …/comity/config.json
✔ server             reachable in 84 ms
✔ token              valid for diego@acme.com (org acme)
✔ git                /home/diego/code/acme-api → github.com/acme/acme-api
✔ claude_code hooks  all 6 events installed
✔ claude_code mcp    configured in /home/diego/code/acme-api/.mcp.json
✔ codex hooks        all 6 events installed (Codex runs them only after you approve them in /hooks)
✔ codex mcp          configured in /home/diego/code/acme-api/.codex/config.toml
✔ round trip         session_start → allow in 112 ms (session 0199…)
✔ CLI up to date     0.9.0 is the latest release

✔ All checks passed.

Follow any › hint it prints. See Troubleshooting for each failure.

6. Start your agent

  • Claude Code: start claude in the repo, accept the folder trust prompt and approve the comity MCP server.
  • Codex: start codex, trust the project, then open /hooks and approve the comity hooks. Codex skips them until you do.

At session start the agent receives a Comity briefing, including the line Your Comity session: <uuid>. Ask the agent "What did Comity tell you at session start?" to see it. Your session now appears in the dashboard under Activity.

7. See your first conflict

Comity compares agents working in different checkouts: different developers, or one developer with two worktrees. To try it alone, make a second worktree:

Terminal
git worktree add ../acme-api-b -b try-comity-b
  1. In the original checkout, ask an agent to change a function, for example: "Add a currency parameter to formatPrice in src/money.ts."
  2. In ../acme-api-b, start a second agent and ask it to change the same function differently: "Rename formatPrice to formatAmount."

After the second agent's edit, Comity adds context like this to that agent:

## Comity update — system-generated for `acme/acme-api`
Lines starting with "•" are facts generated by Comity.
### New conflicts from this change
• CF-1 symbol_overlap [warn] · open · with your other session (INT-1, Claude Code) · `sym:ts:src/money.ts#formatPrice` · detected just now
  · …

The conflict also appears in the dashboard under Conflicts, with both sides, what overlaps and a suggested next step. The agents can now coordinate with message_send, and you can acknowledge or resolve the conflict from either side. Clean up with git worktree remove ../acme-api-b.

8. Invite your team

In the dashboard, Team → Invite teammates. Each teammate installs the CLI and runs comity login; the repo config is already committed.

Next

  • How it works: what happens on each agent event.
  • Agent instructions: a snippet for CLAUDE.md / AGENTS.md that makes agents use the MCP tools well.
  • Policies: make protected paths block, require intents, tune severities.