> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/integrations/kiro.md).

# Kiro

Kiro is a first-class Observal harness integration. Observal can install Kiro agents, configure MCP servers, add hooks, expose skills, and collect Kiro session telemetry.

***

## Overview

Kiro agent profiles are JSON files. Project agents live in `.kiro/agents/`. User agents live in `~/.kiro/agents/`.

When Observal installs a Kiro agent, it writes hook commands into that agent JSON. The default hooks run the shared `observal_cli.hooks.session_push --harness kiro` entry point for `userPromptSubmit` and `stop`.

The hook reads Kiro session JSONL files from `~/.kiro/sessions/cli/`. It reads only new lines since the last push and sends them to Observal.

***

## Supported capabilities

| Capability      | Support                                                               |
| --------------- | --------------------------------------------------------------------- |
| Agent profiles  | Project and user scope                                                |
| Hook bridge     | `userPromptSubmit` and `stop` by default                              |
| Custom hooks    | `agentSpawn`, `userPromptSubmit`, `preToolUse`, `postToolUse`, `stop` |
| MCP servers     | `.kiro/settings/mcp.json` and `~/.kiro/settings/mcp.json`             |
| Agent prompt    | Registry prompts are embedded in the generated Kiro agent profile     |
| Guidance files  | Scanned from steering files and `AGENTS.md`, not overwritten          |
| Skills          | `.kiro/skills/{name}/SKILL.md` and `~/.kiro/skills/{name}/SKILL.md`   |
| Session parsing | Kiro JSONL parser                                                     |
| Telemetry       | Kiro session transcripts delivered through hooks and reconciliation   |
| Model selection | Registry-backed Kiro model catalog                                    |

***

## Setup

### 1. Install the Observal CLI

```bash
uv tool install observal-cli
# or: pipx install observal-cli
```

### 2. Authenticate

```bash
observal auth login
```

This writes credentials to `~/.observal/config.json`.

### 3. Pull an agent into Kiro

```bash
observal agent pull <agent-name> --harness kiro
```

Kiro's default scope is user scope. By default, the agent is written to `~/.kiro/agents/{name}.json`.

To install into the current project:

```bash
observal agent pull <agent-name> --harness kiro --scope project
```

Project agents are written to `.kiro/agents/{name}.json`.

### 4. Refresh Kiro hooks

Pull the agent again to refresh its Observal hook commands.

Kiro attribution is installed per pulled agent because each hook command carries that agent's Observal UUID. `doctor patch` does not install generic Kiro hooks.

***

## Config paths

| Purpose              | Project scope                             | User scope                                |
| -------------------- | ----------------------------------------- | ----------------------------------------- |
| Agent profile        | `.kiro/agents/{name}.json`                | `~/.kiro/agents/{name}.json`              |
| Guidance files       | `.kiro/steering/*.md`, `AGENTS.md`        | `~/.kiro/steering/*.md`                   |
| MCP config           | `.kiro/settings/mcp.json`                 | `~/.kiro/settings/mcp.json`               |
| Skill definition     | `.kiro/skills/{name}/SKILL.md`            | `~/.kiro/skills/{name}/SKILL.md`          |
| Hook config          | Embedded in `.kiro/agents/{name}.json`    | Embedded in `~/.kiro/agents/{name}.json`  |
| Custom hook scripts  | `.kiro/hooks/`                            | `~/.kiro/hooks/`                          |
| Session JSONL        | `~/.kiro/sessions/cli/{session_id}.jsonl` | `~/.kiro/sessions/cli/{session_id}.jsonl` |
| Credit metadata      | `~/.kiro/sessions/cli/{session_id}.json`  | `~/.kiro/sessions/cli/{session_id}.json`  |
| Observal credentials | `~/.observal/config.json`                 | `~/.observal/config.json`                 |
| Last session cache   | `~/.observal/.kiro-session`               | `~/.observal/.kiro-session`               |

Kiro MCP configs use the `mcpServers` key.

***

## Hook spec

Observal writes the telemetry hooks inside each Kiro agent JSON:

```json
{
  "hooks": {
    "userPromptSubmit": [
      {
        "command": "OBSERVAL_AGENT_ID=<agent-uuid> python -m observal_cli.hooks.session_push --harness kiro"
      }
    ],
    "stop": [
      {
        "command": "OBSERVAL_AGENT_ID=<agent-uuid> python -m observal_cli.hooks.session_push --harness kiro"
      }
    ]
  }
}
```

On non-Windows platforms, generated server config may use `python3` instead of `python`. During `observal agent pull`, the CLI rewrites Observal hook commands to use the active Python interpreter.

### Attribution

Kiro does not expose a reliable active Observal agent in its session JSONL. The per-agent hook command is the source of truth.

1. `observal agent pull` writes the agent UUID into the Kiro hook command as `OBSERVAL_AGENT_ID`.
2. The shared session hook reads that UUID when Kiro fires `userPromptSubmit` or `stop`.
3. The CLI selects the active server URL under `registries` in `~/.observal/lockfile.json`, then looks up the UUID under that registry's `kiro` harness.
4. The session payload is sent with the lockfile agent id and version.
5. If the UUID is missing or no lockfile entry exists, the session is left unattributed instead of guessing from the current directory.

### Event map

| Observal event     | Kiro event         |
| ------------------ | ------------------ |
| `SessionStart`     | `agentSpawn`       |
| `UserPromptSubmit` | `userPromptSubmit` |
| `PreToolUse`       | `preToolUse`       |
| `PostToolUse`      | `postToolUse`      |
| `Stop`             | `stop`             |

`preToolUse` and `postToolUse` hooks can include a `matcher`. Observal uses `*` when no matcher is set.

***

## Session push behavior

Kiro uses the shared acknowledged session delivery engine:

1. Resolve the Kiro session ID from the hook payload or `~/.observal/.kiro-session`.
2. Find `~/.kiro/sessions/cli/{session_id}.jsonl` through the Kiro adapter.
3. Read complete records after the acknowledged byte/line cursor.
4. Persist new batches to `~/.observal/telemetry_buffer.db` before network delivery.
5. Retry batches idempotently until the server returns a contiguous checkpoint covering them.
6. Advance the local cursor only to that acknowledged checkpoint.
7. Recover missing or corrupt local state from the authenticated server checkpoint.
8. On finalization, compare the SHA-256 audit manifest and replay any affected range.

On `stop`, a delayed stable-file pass captures late records and finalizes the cursor. The adapter also reads `~/.kiro/sessions/cli/{session_id}.json` and durably sends Kiro credit usage, including when no transcript lines were added by the final hook.

***

## Agent profile format

Observal generates Markdown agent profiles like this:

```markdown
---
name: my-agent
model: claude-sonnet-4
---

You are a Kiro agent with the following specialization...
```

The `model` field is present when a model is resolved for the agent.

***

## Skill file format

Kiro skills live at:

| Scope   | Path                             |
| ------- | -------------------------------- |
| Project | `.kiro/skills/{name}/SKILL.md`   |
| User    | `~/.kiro/skills/{name}/SKILL.md` |

Example:

```markdown
---
description: "Runs the project test suite"
task_type: testing
---

# Run Tests

Run `pytest -q` from the project root.
```

***

## Caveats

**Guidance files are scan-only.** Observal layers Kiro steering files and `AGENTS.md` as context, but does not overwrite them during pull.

**Hooks are per agent.** Pulling a new agent includes telemetry hooks automatically, with `OBSERVAL_AGENT_ID` bound to that agent's UUID. Pull the agent again to replace an older Kiro-specific push command with the shared acknowledged exporter. `doctor patch` does not install generic Kiro attribution hooks.

**Default scope is user.** `observal agent pull <agent-name> --harness kiro` writes to `~/.kiro/agents/` unless `--scope project` is set.

**No Claude Code subagent layout.** Kiro reads `~/.kiro/sessions/cli/{session_id}.jsonl`. It does not scan Claude Code's `subagents/` directory.

**MCP config is Kiro-specific.** Kiro uses `.kiro/settings/mcp.json` and `~/.kiro/settings/mcp.json`, not Claude Code MCP paths.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.observal.io/integrations/kiro.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.