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

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

2. Authenticate

observal auth login

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

3. Pull an agent into Kiro

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:

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:

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

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

---
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.