> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kiro

> Trace Kiro CLI agent turns, tool calls, and credit usage in Arize AX using the Arize Coding Harness Tracing.

> Trace Kiro CLI agent turns, tool calls, and credit usage in Arize AX for full observability.

[Kiro](https://kiro.dev) is AWS's agentic IDE and CLI for spec-driven development. The [Arize Coding Harness Tracing](https://github.com/Arize-ai/coding-harness-tracing) registers hooks on a Kiro agent and exports [OpenInference](https://github.com/Arize-ai/openinference) spans to Arize AX or Phoenix. Each agent turn is captured as an LLM span with tool calls, model info, credit cost, and turn duration.

## Launch Arize AX

To get started, sign up for a free [Arize AX account](https://app.arize.com/auth/join) and get your Space ID and API Key:

1. Log in at [app.arize.com](https://app.arize.com)
2. Click **Settings** and copy the **Space ID**
3. Open the **API Keys** tab and create or copy an API key

## Install

### Curl installer

**macOS / Linux:**

```bash theme={null}
curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- kiro
```

**Windows (PowerShell):**

```powershell theme={null}
iwr -useb https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.bat -OutFile $env:TEMP\install.bat
& $env:TEMP\install.bat kiro
```

### Local clone

```bash theme={null}
git clone https://github.com/Arize-ai/coding-harness-tracing.git
cd coding-harness-tracing
./install.sh kiro          # macOS / Linux
install.bat kiro           # Windows
```

The installer prompts you through:

1. **Agent name** — the Kiro agent to install hooks into (default: `arize-traced`)
2. **Set as default** — whether to run `kiro-cli agent set-default <name>` so the agent is used by default
3. **Backend** — Phoenix or Arize AX, plus endpoint and credentials
4. **Project name** — project name in your backend (default: `kiro`)
5. **User ID** — optional user identifier added to all spans
6. **Logging** — whether to include prompt text, tool content, and tool details in spans

Once installed, run Kiro as usual. If you set the traced agent as the default during install:

```bash theme={null}
kiro-cli chat
```

Otherwise, point Kiro at the traced agent explicitly:

```bash theme={null}
kiro-cli chat --agent arize-traced
```

## Configuration

Credentials live under `harnesses.kiro` in `~/.arize/harness/config.yaml` (written by the installer). Environment variables override values in `config.yaml` and can be set in your shell profile so they apply to every Kiro session.

### Phoenix (self-hosted)

```bash theme={null}
export PHOENIX_ENDPOINT="http://localhost:6006"
export ARIZE_PROJECT_NAME="kiro"
export ARIZE_TRACE_ENABLED="true"
```

### Arize AX (cloud)

```bash theme={null}
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_PROJECT_NAME="kiro"
export ARIZE_TRACE_ENABLED="true"
```

### Redaction controls

Each `ARIZE_LOG_*` flag accepts `"true"` or `"false"` and defaults to `"true"`. Set to `"false"` to opt out per category:

```bash theme={null}
export ARIZE_LOG_PROMPTS="false"
export ARIZE_LOG_TOOL_DETAILS="false"
export ARIZE_LOG_TOOL_CONTENT="false"
```

| Flag                     | Redacts                                 |
| :----------------------- | :-------------------------------------- |
| `ARIZE_LOG_PROMPTS`      | User prompt and assistant response text |
| `ARIZE_LOG_TOOL_DETAILS` | Tool names and arguments                |
| `ARIZE_LOG_TOOL_CONTENT` | Tool call output content                |

The same flags can be set in `config.yaml` under `harnesses.kiro.logging` as `log_prompts`, `log_tool_details`, and `log_tool_content` — env vars take precedence.

## Observe

Once tracing is enabled, Kiro activity is streamed to Arize AX. You'll see:

* **Turn traces** — each agent turn (user prompt to assistant response) as a parent LLM span
* **Tool call spans** — one per pre/post tool event pair, parented to the LLM turn
* **Session grouping** — all turns from the same Kiro session grouped by `session.id`
* **Credit cost** — Kiro meters in credits rather than tokens; cost is captured as `kiro.cost.credits`
* **Model and duration** — `llm.model_name`, `kiro.turn_duration_ms`, and `kiro.context_usage_percentage` from the session sidecar

### Hooks Captured

| Hook               | Span Kind | Description                                            |
| :----------------- | :-------- | :----------------------------------------------------- |
| `agentSpawn`       | CHAIN     | Agent spawned, trace/tool counters reset               |
| `userPromptSubmit` | CHAIN     | User prompt captured, session lazy-initialized         |
| `preToolUse`       | TOOL      | Tool invocation started, records tool name and input   |
| `postToolUse`      | TOOL      | Tool invocation completed, records output and duration |
| `stop`             | LLM       | Model response completed with input/output values      |

### Span attributes

LLM spans are enriched from the session sidecar at `~/.kiro/sessions/cli/<session_id>.json` with model name, cost in credits, metering usage, and turn duration. Enrichment is fail-soft — if the sidecar is unavailable, the span is emitted with basic attributes only.

| Attribute                       | Description                        |
| :------------------------------ | :--------------------------------- |
| `session.id`                    | Kiro session UUID                  |
| `llm.model_name`                | Model ID from the session sidecar  |
| `kiro.cost.credits`             | Cost in credits from metering data |
| `kiro.metering_usage`           | Full metering usage JSON           |
| `kiro.turn_duration_ms`         | Turn duration in milliseconds      |
| `kiro.agent_name`               | Name of the Kiro agent             |
| `kiro.context_usage_percentage` | Context window usage percentage    |

## Known limitations

* **Token counts are 0.** Kiro CLI does not report prompt or completion token counts in current versions and meters in credits instead. Token count attributes are omitted when 0; see `kiro.cost.credits`.
* **FIFO tool matching.** Kiro does not expose a tool-call ID, so pre/post tool events are matched using a FIFO stack. This assumes serial tool execution within a session.
* **Per-workspace agents not supported.** Only global agents under `~/.kiro/agents/` are instrumented.

## Reference

For the full list of environment variables, default file paths, and troubleshooting steps, see the [Kiro tracing README](https://github.com/Arize-ai/coding-harness-tracing/blob/main/tracing/kiro/README.md).

## Uninstall

```bash theme={null}
curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- uninstall kiro
```

Uninstall removes hook entries from every Kiro agent file. If the `arize-traced` agent was created by the installer, that agent file is deleted; pre-existing agents are preserved.

## Resources

<CardGroup>
  <Card icon="github" href="https://github.com/Arize-ai/coding-harness-tracing" title="Arize Coding Harness Tracing" horizontal />

  <Card icon="github" href="https://github.com/Arize-ai/openinference" title="OpenInference" horizontal />

  <Card icon="book-open" href="https://kiro.dev" title="Kiro Documentation" horizontal />
</CardGroup>