# Kiro

> Set up Comity agent hooks, MCP and a steering file for Kiro IDE and Kiro CLI.

Kiro (IDE 1.x and CLI V3) gets hooks on session start, prompts, file writes and shell commands, the Comity MCP server, and an always-included steering file.

## Set up

```sh
cd your-repo
comity init --tools kiro
git add .kiro/hooks/comity.json .kiro/settings/mcp.json .kiro/steering/comity.md
git commit -m "Set up Comity for Kiro"
```

Then, in Kiro IDE, enable MCP support in Settings (search "MCP").

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

## What init writes

### `.kiro/hooks/comity.json`

Kiro loads every `.kiro/hooks/*.json`; this file is Comity's alone and is rewritten by init. Shown for one hook:

```json
{
  "version": "v1",
  "hooks": [
    {
      "name": "Comity PreToolUse (write)",
      "trigger": "PreToolUse",
      "matcher": "write",
      "action": {
        "type": "command",
        "command": "node -e \"<launcher>\" hook --tool kiro --event PreToolUse"
      },
      "timeout": 5
    }
  ]
}
```

| Trigger | Matcher | Timeout (s) |
|---|---|---|
| `SessionStart` | | 5 |
| `UserPromptSubmit` | | 5 |
| `PreToolUse` | `write`, `shell` (one hook each) | 5 |
| `PostToolUse` | `write`, `shell` (one hook each) | 10 |
| `Stop` | | 10 |
| `SessionEnd` (CLI V3) | | 10 |

`write` and `shell` are Kiro's built-in tool tags (`fs_write`, `str_replace`, `execute_bash`, `execute_pwsh`, …). `<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 and passes exit code `2` through.

### `.kiro/settings/mcp.json`

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

Other servers in the file are kept. The server is a local stdio process: `comity mcp` relays Kiro's MCP traffic to `https://api.comity.so/mcp` with the token from `comity login` (`COMITY_TOKEN`/`COMITY_SERVER` override it when set). The entry is the same on every OS.

### `.kiro/steering/comity.md`

The [agent instructions](/docs/agents/best-practices) with `inclusion: always` front matter, so every Kiro session reads them.

## What your agent sees

Kiro hooks speak exit codes and plain text, not JSON:

- **Session start and each prompt**: the briefing printed on stdout, which Kiro adds to the agent's context.
- **Before a write or shell command**: a block exits with code `2` and Comity's reason on stderr; Kiro cancels the tool call and gives the reason to the model. Warnings are held for the next prompt.
- **After a write or shell command**: Kiro ignores hook output here, so new conflicts and messages arrive with the next prompt.

## Verify

```sh
comity doctor
```

Expect `kiro hooks  all 8 hooks installed`, `kiro mcp  configured in …/.kiro/settings/mcp.json` and `kiro steering  .kiro/steering/comity.md is current`. In the IDE, the Agent Hooks panel lists the Comity hooks; in Kiro CLI use `/hooks` and `/mcp`.

## Limits

- CLI V3 prompt hooks can't block a prompt (Comity never blocks prompts anyway).
- Kiro Web sessions don't run hooks; they still load `.kiro/settings/mcp.json` and the steering file.
- Kiro doesn't document which shell runs hook commands on Windows. If it is Windows PowerShell 5.1 (`-Command`), PowerShell turns exit code `2` into `1`, and Kiro treats a non-2 exit on `PreToolUse` as a warning: a block then reaches you as a warning and the tool call proceeds. sh, bash and cmd pass `2` through.
- Docs: [Hooks](https://kiro.dev/docs/hooks/), [Hook types](https://kiro.dev/docs/hooks/types/), [Hook actions](https://kiro.dev/docs/hooks/actions/), [MCP configuration](https://kiro.dev/docs/mcp/configuration/), [Steering](https://kiro.dev/docs/steering/).