# Factory Droid

> Set up Comity hooks, MCP and AGENTS.md instructions for Factory's Droid CLI.

Droid's hooks use the same events and JSON output as Claude Code, so it gets the full integration: hooks on session start, prompts, edits and shell commands, the Comity MCP server, and an instructions block in `AGENTS.md`.

## Set up

```sh
cd your-repo
comity init --tools droid
git add .factory/hooks.json .factory/mcp.json AGENTS.md
git commit -m "Set up Comity for Droid"
```

Droid snapshots hooks at startup; restart it if it was running, and check the **Project** tab of `/hooks`.

No token is written anywhere and none needs exporting: `comity login` on each machine is enough.

## What init writes

### `.factory/hooks.json`

The standalone hooks file is keyed directly by event name. Your own hooks are kept; rerunning init replaces only Comity's handlers. Shown for one event:

```json
{
  "PreToolUse": [
    {
      "matcher": "Create|Edit|ApplyPatch|Execute",
      "hooks": [
        {
          "type": "command",
          "command": "node -e \"<launcher>\" hook --tool droid --event PreToolUse",
          "timeout": 5
        }
      ]
    }
  ]
}
```

| Event | Matcher | Timeout (s) |
|---|---|---|
| `SessionStart` | | 5 |
| `UserPromptSubmit` | | 5 |
| `PreToolUse` | `Create\|Edit\|ApplyPatch\|Execute` | 5 |
| `PostToolUse` | `Create\|Edit\|ApplyPatch\|Execute` | 10 |
| `Stop` | | 10 |
| `SessionEnd` | | 10 |

Droid reads `hooks` from `.factory/settings.json` only when `hooks.json` is absent, so init always writes `hooks.json`. `<launcher>` is a one-line Node script that runs `comity` through the system shell, so the same file works on every OS (Node must be on `PATH`; the CLI needs it anyway). It exits quietly when `comity` isn't installed.

### `.factory/mcp.json`

```json
{
  "mcpServers": {
    "comity": { "type": "stdio", "command": "node", "args": ["-e", "<launcher>", "mcp"] }
  }
}
```

The server is a local stdio process: `comity mcp` relays Droid's MCP traffic to `https://api.comity.so/mcp` with the token from `comity login` (`COMITY_TOKEN`/`COMITY_SERVER` override it when set), the same login the hooks use. The entry is the same on every OS.

### `AGENTS.md`

A block between `<!-- comity:start -->` and `<!-- comity:end -->` with the [agent instructions](/docs/agents/best-practices). The rest of the file is untouched.

## What your agent sees

- **Session start and each prompt**: the briefing as added context.
- **Before an edit or shell command**: a block denies the call (`permissionDecision: "deny"`) with Comity's reason. Warnings are held for the next prompt or tool result.
- **After an edit or shell command**: new conflicts, messages and answers as `additionalContext`.

## Verify

```sh
comity doctor
```

Expect `droid hooks  all 6 events installed`, `droid mcp  configured in …/.factory/mcp.json` and `droid rules  AGENTS.md has the Comity block`. In Droid, `/hooks` and `/mcp` list `comity`.

## Limits

- Org-managed settings with `allowManagedHooksOnly` ignore project hooks; ask your admin to add the Comity hooks to managed settings.
- Docs: [Droid hooks](https://docs.factory.ai/harness/hooks), [Droid MCP](https://docs.factory.ai/harness/mcp).