Kiro

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

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:

{
  "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
    }
  ]
}

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

{
  "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 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

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, Hook types, Hook actions, MCP configuration, Steering.