# Quickstart

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

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](https://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

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

## 3. Sign in

```sh
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:

```text
✔ 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

```sh
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`:

```sh
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

```sh
comity doctor
```

```text
✔ 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](/docs/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:

```sh
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:

```text
## 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](/docs/how-it-works): what happens on each agent event.
- [Agent instructions](/docs/agents/best-practices): a snippet for `CLAUDE.md` / `AGENTS.md` that makes agents use the MCP tools well.
- [Policies](/docs/admin/policies): make protected paths block, require intents, tune severities.