Kiro CLI Provider

July 8, 2026 · View on GitHub

Overview

The Kiro CLI provider enables CLI Agent Orchestrator (CAO) to work with Kiro CLI, an AI-powered coding assistant that operates through agent-based conversations with customizable profiles.

Quick Start

Prerequisites

  1. AWS Credentials: Kiro CLI authenticates via AWS
  2. Kiro CLI: Install the CLI tool
  3. tmux: Required for terminal management
# Install Kiro CLI
npm install -g @anthropic-ai/kiro-cli

# Verify authentication
kiro-cli --version

Using Kiro CLI Provider with CAO

# Start the CAO server
cao-server

# Launch a Kiro CLI-backed session (agent profile is required)
cao launch --agents developer --provider kiro_cli

Via HTTP API:

curl -X POST "http://localhost:9889/sessions?provider=kiro_cli&agent_profile=developer"

Note: Kiro CLI requires an agent profile — it cannot be launched without one.

Features

Status Detection

The Kiro CLI provider detects terminal states by analyzing ANSI-stripped output:

  • IDLE: Agent prompt visible (legacy [profile_name] > or new TUI ask a question, or describe a task), no response content
  • PROCESSING: No idle prompt found in output (agent is generating response)
  • COMPLETED: Green arrow (>) response marker (legacy) or ▸ Credits: marker (TUI) present + idle prompt after it
  • WAITING_USER_ANSWER: Permission prompt visible (Allow this action? [y/n/t]:)
  • ERROR: Known error indicators present (e.g., "Kiro is having trouble responding right now")

Status detection priority: no prompt → PROCESSING → ERROR → WAITING_USER_ANSWER → COMPLETED → IDLE.

The provider supports both the legacy UI prompt format and the new TUI format for all status detection and message extraction.

Dynamic Prompt Pattern

The provider supports two prompt formats:

Legacy UI (used with --legacy-ui flag):

[developer] >          # Basic prompt
[developer] !>         # Prompt with pending changes
[developer] 50% >      # Prompt with progress indicator
[developer] λ >        # Prompt with lambda symbol
[developer] 50% λ >    # Combined progress and lambda

Pattern: \[{agent_profile}\]\s*(?:\d+%\s*)?(?:\u03bb\s*)?!?>\s*

New TUI (default in latest Kiro CLI):

code_supervisor · claude-opus-4.6-1m · ◔ 1%
 ask a question, or describe a task ↵

The new TUI idle state is detected by the ask a question, or describe a task pattern, and completion is detected by the ▸ Credits: marker followed by an idle prompt. The provider launches in TUI mode by default and auto-detects which format is active.

Message Extraction

The provider uses a dual-path extraction strategy:

Legacy mode (green arrow markers):

  1. Strip ANSI codes from output
  2. Find all green arrow (>) markers (response start)
  3. Take the last one
  4. Find the next idle prompt after it (response end)
  5. Extract and clean text between them

TUI mode (separator + Credits markers):

  1. Find the last ▸ Credits: line (response end marker)
  2. Find the last separator (────) before Credits (response start area)
  3. Extract text between separator and Credits
  4. Skip the first paragraph (user message echo)
  5. Clean remaining text (ANSI, escape sequences, control characters)

The provider tries legacy extraction first; if no green arrows are found, it falls back to TUI extraction. This is backward compatible with --legacy-ui wrapper scripts.

Permission Prompts

Kiro CLI shows Allow this action? [y/n/t]: prompts for sensitive operations (file edits, command execution). The provider detects these as WAITING_USER_ANSWER status. Unlike Claude Code, Kiro CLI does not have a trust folder dialog.

Configuration

Agent Profile (Required)

Kiro CLI always requires an agent profile. CAO passes it via:

kiro-cli chat --agent {profile_name}

The profile name determines the prompt pattern used for status detection. Built-in profiles include developer and reviewer.

Launch Command

The provider launches using kiro-cli's default UI, with automatic --legacy-ui fallback:

kiro-cli chat --agent developer

The provider auto-detects whether the terminal is in legacy or TUI mode and uses the appropriate detection patterns. If initialization times out, the provider automatically exits and retries with --legacy-ui. Both TUI and legacy detection patterns are fully supported.

Implementation Notes

  • ANSI stripping: All pattern matching operates on ANSI-stripped output for reliability
  • Green arrow pattern: ^>\s* matches the start of agent responses (after ANSI stripping)
  • Generic prompt pattern: \x1b\[38;5;13m>\s*\x1b\[39m\s*$ matches the purple-colored prompt in raw output (used for log monitoring)
  • Error detection: Checks for known error strings like "Kiro is having trouble responding right now"
  • Multi-format cleanup: Extraction strips ANSI codes, escape sequences, and control characters
  • Exit command: /exit via POST /terminals/{terminal_id}/exit

Status Values

  • TerminalStatus.IDLE: Ready for input
  • TerminalStatus.PROCESSING: Working on task
  • TerminalStatus.WAITING_USER_ANSWER: Waiting for permission confirmation
  • TerminalStatus.COMPLETED: Task finished
  • TerminalStatus.ERROR: Error occurred

End-to-End Testing

The E2E test suite validates handoff, assign, and send_message flows for Kiro CLI.

Running Kiro CLI E2E Tests

# Start CAO server
uv run cao-server

# Run all Kiro CLI E2E tests
uv run pytest -m e2e test/e2e/ -v -k kiro_cli

# Run specific test types
uv run pytest -m e2e test/e2e/test_handoff.py -v -k kiro_cli
uv run pytest -m e2e test/e2e/test_assign.py -v -k kiro_cli
uv run pytest -m e2e test/e2e/test_send_message.py -v -k kiro_cli
uv run pytest -m e2e test/e2e/test_supervisor_orchestration.py -v -k KiroCli -o "addopts="

Troubleshooting

Common Issues

  1. "Agent profile required" Error:

    • Kiro CLI cannot be launched without an agent profile
    • Always specify --agents when launching: cao launch --agents developer --provider kiro_cli

  2. Permission Prompts Blocking:

    • Kiro CLI shows [y/n/t] prompts for operations
    • The provider detects these as WAITING_USER_ANSWER
    • In multi-agent flows, the supervisor or user must handle these

  3. Authentication Issues:

    # Verify AWS credentials
aws sts get-caller-identity
# Set credentials via environment
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=...

  4. Prompt Pattern Not Matching:

    • The provider supports both legacy ([name] >) and new TUI (ask a question, or describe a task) formats
    • TUI mode is the default; the provider auto-detects which format is active
    • If you need legacy mode, add --legacy-ui via a wrapper script
    • Check with: kiro-cli chat --agent your_profile

  5. JSON-Only Agent Profiles (AIM-Installed):

    • Agents installed via AIM (Agent Install Manager) may only have .json profiles (e.g., ~/.kiro/agents/librarian/agent-spec.json)
    • CAO's load_agent_profile() primarily scans for .md files
    • If the agent is not found, CAO gracefully falls back — kiro-cli resolves .json profiles natively
    • As a workaround, you can create a stub .md file alongside the .json profile

kiro-cli 2.11+ Notes

Starting with kiro-cli 2.11, the TUI changed how it accepts pasted input and how it renders the processing indicator. CAO's kiro_cli provider handles these:

  • Paste submission: kiro 2.11 needs two Enter keystrokes after a bracketed paste to submit the message (first Enter finalizes the paste, second submits). The provider sets paste_enter_count = 2 and paste_submit_delay = 1.0s. Older kiro versions submitted on a single Enter.
  • Processing indicator: kiro 2.11 replaced "Kiro is working" with "Thinking..." (with an optional "(esc to cancel)" suffix). The provider matches either variant in TUI_PROCESSING_PATTERN.
  • Idle placeholder always visible: The "ask a question or describe a task" placeholder text remains in the raw buffer even during processing. The provider's Check 6 in get_status() requires a bordered response box (two separators + ≥2 content lines between them) before a bare idle-prompt match is treated as COMPLETED — otherwise the worker would be torn down within seconds of a task being sent.
  • Spinner animation floods the event bus: kiro 2.11's TUI redraws a braille spinner (⠋⠙⠹⠸⠼⠴⠦⠧) roughly 10 times per second while an agent is thinking. Each redraw is a separate FIFO write. Without coalescing, that produces thousands of terminal.{id}.output events per turn — enough to overflow the shared async queue and drop the worker's real state transitions along with the animation noise. CAO's FIFO reader batches chunks arriving within a 50ms window into one publish (_COALESCE_WINDOW), reducing publish rate ~20x during bursts. Consumers see the same bytes in the same order; only the event boundaries change. If handoff/assign start hanging on a newer kiro release, check whether the animation frame rate increased beyond what 50ms can absorb.

If you upgrade kiro-cli and handoffs stop working (worker gets killed prematurely, or the task sits unsent in the input box), check whether the paste-submit behavior or processing-indicator text changed in the new version and update the provider constants accordingly.