Kiro CLI v2 — Power User Guide

🧠

Mental Model

How Kiro CLI v2 actually works under the hood

Kiro CLI is not a chat wrapper. It's a directory-aware agent runtime with a layered context system, lifecycle hooks, and first-class support for parallel task execution. The more of these layers you configure, the less you prompt.

Layer 1

Global Steering (~/.kiro)

Always-on personal conventions. Your coding style, commit format, PR preferences. Follows you to every workspace.

Layer 2

Workspace Steering (.kiro/steering/)

Project-specific patterns. API conventions, testing standards, domain knowledge per repo.

Layer 3

Custom Agent Config

Role-specific personas with locked tool permissions, scoped file access, and embedded resources.

Layer 4

Hooks (Lifecycle)

Commands that fire on spawn, prompt submit, pre/post tool use, and stop. Fully automated side effects.

Key insight: Every prompt you type that starts with "remember we use..." or "please follow our pattern for..." is context that should be in a steering file. Stop re-explaining. Encode it once.

The Upgrade Path

Ask questions

→

Use @path + /editor

→

Steering files

→

Custom agents

→

Hooks + Subagents

→

Headless CI/CD

Each step multiplies the leverage of everything before it. Use the sidebar to work through each layer.

⌨️

Slash Commands

The full in-session command vocabulary

Command	What it does	Power tip
/editor	Open $EDITOR for long-form prompt input	Use for complex PRD-style prompts. Write the full spec, paste it, let the agent plan.
/context add	Inject a file or URL into current session context	Pull in a ticket, PR diff, or design doc mid-conversation.
/context show	List everything currently in the context window	Audit what the agent actually knows before a big task.
/agent swap	Switch to a different custom agent in-session	Start with default, gather info, then swap to specialist agent for the actual work.
/chat new	Fresh conversation, keep working in same terminal	Parallel work — start new thread without losing your current session.
/save [name]	Persist current conversation to disk	Checkpoint before exploring a risky approach. Load it back if things go wrong.
/load [name]	Restore a saved conversation	Resume a complex multi-step investigation exactly where you left it.
/code init	Initialize LSP for the current workspace	Unlocks find-references, rename, hover docs. Run once per project.
/experiment	Toggle experimental features on/off	Enable persistent memory, TODO tracking, extended reasoning.
/introspect	Ask Kiro about its own capabilities	Always accurate — pulls from live docs, not training data.

Power Combo: /editor + /agent swap

Write a detailed spec in /editor using a planning agent, then /agent swap to your implementation agent to execute it. Separates intent from execution.

📁

Context & @path Injection

Eliminate context-gathering prompts. Inject exactly what the agent needs.

@path Inline Injection

Reference files or directories directly in your prompt. Content expands before sending — no tool call, no extra tokens used on navigation.

in-prompt
# Inject a single file
Review @src/handlers/checkout.py for security issues

# Inject a directory tree
What's the structure of @src/api/ and which module handles auth?

# Combine multiple files
Compare @src/old-service.py and @src/new-service.py — what changed?

Session Context Management

slash commands
/context add https://your-wiki.internal/page-123
/context add ./docs/api-spec.md
/context show    # audit current window

Token discipline: Use @path for files you need read, /context add for reference docs, and knowledge bases (in custom agents) for searchable corpora. Don't dump everything into the chat window.

Knowledge Bases (in Custom Agents)

For large doc sets (internal wikis, architecture docs, ADRs), configure a knowledge base resource in your agent. Kiro semantically indexes and retrieves — far more efficient than injecting whole directories.

agent config
"resources": [
  {
    "type": "knowledgeBase",
    "source": "file://./docs",
    "name": "ArchDocs",
    "description": "Architecture decisions and runbooks",
    "indexType": "best",
    "autoUpdate": true
  }
]

Multi-Session Picker

Kiro v2 supports multiple concurrent sessions. Use the interactive session picker to switch between ongoing investigations — great for keeping "debug prod" separate from "implement feature X".

🎯

Steering Files

Persistent knowledge that eliminates repetitive prompting forever

Steering files are markdown docs in .kiro/steering/ (workspace) or ~/.kiro/steering/ (global). Kiro loads them automatically on every session. One-time investment, infinite payoff.

Global Steering (~/.kiro/steering/)

Your personal engineering constitution. Applies everywhere.

~/.kiro/steering/preferences.md
# My Engineering Preferences

## Code style
- Python: Black formatting, type hints everywhere, docstrings for public methods
- Always prefer explicit over implicit
- Error messages must include context and recovery hint

## Commit format
- Conventional commits: feat/fix/chore/refactor/docs
- Subject line ≤72 chars, imperative mood
- Always reference ticket ID if one exists

## PR discipline
- PRs should be small and focused; split if >400 lines changed
- Tests must pass before requesting review
- Include "Testing" section in PR body

## Reviewing code
- Prioritize: correctness > security > performance > style
- Call out magic numbers, missing error handling, N+1 queries

Workspace Steering (.kiro/steering/)

Project-specific context. The agent always knows your stack.

api-patterns.md

API Conventions

Your request/response shapes, error format, auth patterns, versioning strategy.

testing-standards.md

Testing Standards

Unit vs integration split, mock approach, required coverage, fixture patterns.

infra-context.md

Infrastructure Context

AWS services in use, Lambda constraints, env vars, deployment flow, key ARNs format.

domain-model.md

Domain Model

Core entities, relationships, business rules. Agent understands your domain without explanation.

Pro move: Ask Kiro to generate its own steering file. Prompt: "Analyze this codebase and create a .kiro/steering/patterns.md that captures our key patterns and conventions." Then review and commit it.

AGENTS.md Standard

Kiro supports the cross-tool AGENTS.md format. If you work across multiple AI tools (Cursor, Claude Code, etc.), a root-level AGENTS.md is always picked up — no config needed.

🤖

Custom Agents

Role-specific agents with scoped tools, context, and personas

Agents are JSON configs in .kiro/agents/. Each agent has a focused persona, pre-approved tools, scoped file access, and embedded resources. Switch mid-session with /agent swap.

Example: AWS/Lambda Specialist

Knows your infra, has AWS tool access, scoped to infrastructure paths only.

.kiro/agents/aws-specialist.json{
  "name": "aws-specialist",
  "description": "Lambda, Step Functions, CloudWatch expert",
  "model": "claude-sonnet-4",
  "prompt": "You are an AWS expert specializing in Lambda, Step Functions, and observability. You know this team uses ADOT Lambda layer, EMF for metrics, and X-Ray for tracing. Always consider cold start impact and Lambda's hard-kill behavior when suggesting solutions.",
  "tools": ["read", "write", "shell", "aws"],
  "allowedTools": ["read", "aws"],
  "toolsSettings": {
    "aws": { "allowedServices": ["lambda", "logs", "xray", "cloudformation"] },
    "write": { "allowedPaths": ["infrastructure/**", "*.yaml"] }
  },
  "resources": [
    "file://.kiro/steering/**/*.md",
    "file://infrastructure/**/*.yaml",
    "file://docs/runbooks/**"
  ],
  "hooks": {
    "agentSpawn": [{ "command": "aws sts get-caller-identity", "cache_ttl_seconds": 300 }]
  }
}

Example: Code Review Agent

.kiro/agents/code-review.json{
  "name": "code-review",
  "prompt": "You are a senior code reviewer. Focus on: correctness, security, missing error handling, performance anti-patterns, and adherence to team standards in the steering files.",
  "tools": ["read", "shell"],
  "toolsSettings": {
    "shell": {
      "allowedCommands": ["git diff", "git log", "grep", "find", "eslint", "pylint"]
    }
  },
  "resources": [
    "file://CONTRIBUTING.md",
    "file://.kiro/steering/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [{ "command": "git diff --name-only HEAD~1" }]
  }
}

Agent Roster Strategy

Agent

Planner

Read-only tools
Full steering context
Generates implementation plans
No write access

Agent

Implementer

Read + Write + Shell
Scoped to src/ paths
LSP enabled
auto-test on stop hook

Agent

Reviewer

Read + Shell (linters only)
Loads coding standards
Spawns on agentSpawn: git diff
Comments on MCP ticket tools

Agent

Debugger

Read + AWS tools
Loads runbooks KB
Access to CloudWatch logs
Incident-focused prompt

🔗

Hooks (Automation)

Lifecycle-driven automation. Like GitHub Actions, but for your local agent.

Hooks fire at defined lifecycle points and receive event JSON via STDIN. Return exit 0 to succeed, exit 2 from a preToolUse hook to block the tool call entirely.

Lifecycle Points

1

agentSpawn

Fires when agent activates. Inject git status, caller identity, last deploy info into context.

2

userPromptSubmit

Fires on every prompt. Auto-inject dynamic context: open tickets, env state, recent errors.

3

preToolUse

Fires before any tool call. Validate, audit-log, or block dangerous operations (exit 2).

4

postToolUse

Fires after tool execution. Auto-format written files, trigger linters, sync state.

5

stop

Fires when agent finishes responding. Run tests, compile, send notifications, update tickets.

High-Value Hook Patterns

auto-format on write"postToolUse": [
  {
    "matcher": "fs_write",
    "command": "black . --quiet && isort . --quiet"
  }
]

run tests on stop"stop": [
  { "command": "npm test -- --passWithNoTests" }
]

audit all bash commands (preToolUse)"preToolUse": [
  {
    "matcher": "execute_bash",
    "command": "{ echo \"$(date) [$SESSION_ID] CMD:\"; cat; } >> ~/.kiro/audit.log"
  }
]

block writes outside src/ (preToolUse, exit 2 = block)"preToolUse": [
  {
    "matcher": "fs_write",
    "command": "python3 -c \"import sys,json; d=json.load(sys.stdin); path=d.get('tool_input',{}).get('path',''); sys.exit(2 if not path.startswith('./src') else 0)\""
  }
]

Context injection via userPromptSubmit: Run a script that fetches the current sprint's open tickets from your MCP tool and injects them into every prompt. The agent always knows what's in-flight.

Cache your hooks: Add "cache_ttl_seconds": 300 to expensive hooks (like AWS identity checks or ticket fetches) to avoid redundant network calls on every prompt.

🔀

Subagents & Parallel Execution

Delegate complex tasks. Run multiple workstreams simultaneously.

Subagents run autonomously with their own context window, keeping the parent agent's context focused. This is Kiro v2's biggest productivity multiplier for complex multi-part work.

Core pattern: Teams are using subagents to parallelize work while protecting the parent agent's context. Think of it as spawning specialized workers that report back, rather than one agent context-switching between tasks.

When to Use Subagents

Parallelizable

Independent feature slices

Implement service A + service B simultaneously in separate contexts. No interference, full speed.

Context isolation

Deep-dive investigations

Send a subagent to trace a bug through 10 files while parent agent continues planning.

Specialized agents

Spawn your custom agents

Parent orchestrates. Subagents use your specialist configs (reviewer, aws-specialist, etc.).

Long-running tasks

Background execution

Generate tests while you write the next feature. Track progress via live status bar.

Live Progress Tracking

Use the TUI (kiro-cli --tui or kiro-cli settings chat.ui "tui") to get a live status bar and task list showing all subagent progress simultaneously. Essential for parallel workflows.

Plan Agent (Built-in)

Kiro v2 ships a built-in Plan agent that breaks complex prompts into structured implementation plans. Before telling it to implement, ask it to plan first:

planning workflow# Phase 1: get the plan
/agent swap kiro_plan
I need to add distributed tracing to our marketing advisor Lambda functions.
Analyze the codebase and produce a sequenced implementation plan.

# Phase 2: review + approve plan
# Phase 3: swap to implementer and execute
/agent swap implementer
Execute task 1 from the plan: instrument the conversational layer.

🔍

Code Intelligence (LSP)

Full IDE-grade code understanding in your terminal

Run /code init once per project to unlock LSP-powered intelligence. Kiro spawns language server processes, maintains a live symbol index, and translates your natural language into LSP queries.

What You Unlock

Find References

"Who calls this?"

Natural language: "What code calls the checkout_session_create function?" — no grep hunting.

Hover Docs

"What does this do?"

"What does the s3Client.putObject method accept?" — API exploration without switching context.

Safe Rename

Refactor confidently

Preview with dry_run before applying. Renames across the entire codebase atomically.

Diagnostics

Type errors surfaced

Agent sees the same errors your IDE would — better, more accurate code generation.

Setup

one-time per project# Run in project root
/code init

# Kiro detects language from package.json, Cargo.toml, pyproject.toml etc.
# Starts LSP server in background, indexes symbols
# Then ask naturally:
What are all the places PlanGraph.execute() is called from?
What methods does the StrategyCatalog class expose?

Best practice: Configure grep allowedPaths in your agent config to constrain symbol search to relevant directories. Avoids noise from node_modules, .venv, generated files.

🧪

Experimental Features

Bleeding edge — enable with /experiment

Toggle experiments with /experiment. These are in active development but often highly useful. May change or be removed.

persistent-memory

Semantic search across past sessions. Find context from conversations weeks ago without re-explaining.

tangent-mode

Conversation checkpoints. Explore a risky approach in a side branch, then return to main flow cleanly.

todo-tracking

Auto-creates and maintains TODO lists during complex tasks. Agent tracks its own progress across a long session.

extended-thinking

Shows step-by-step reasoning for complex problems. Use for architecture decisions or subtle bugs.

Production caution: Don't rely on experimental features in hooks or CI pipelines — they can be toggled off in any release. Use stable features for automation.

TUI Mode (Graduated to Default in v2)

The terminal UI is now the default in v2. Enable permanently with:

kiro-cli settings chat.ui "tui"

# What you get:
# - Live status bar with real-time tool progress
# - Rich markdown rendering with syntax-highlighted code
# - Interactive panels for context / session management
# - Subagent progress tracking
# - --list-models flag to check available models

🤖

Headless Mode & CI/CD

Run Kiro agents in pipelines, containers, and cron jobs

Headless mode (v2) runs Kiro without a browser, using an API key. Same tools, same agents, same MCP servers — fully automated, no human input required.

Setup

environment# Generate API key in Kiro dashboard
export KIRO_API_KEY="your-api-key"

# Run a prompt non-interactively
kiro-cli --headless --prompt "Review changes in the last commit and create a PR comment"

# Pipe output
kiro-cli --headless --prompt "Generate unit tests for src/handlers/" | tee test-gen.log

CI/CD Use Cases

PR Review Bot

Auto-review on push

Trigger your code-review agent on every PR. Posts comments via your ticket MCP tool. Zero human review queue overhead.

Test Generation

Coverage on new code

On merge to main, run your implementer agent to generate tests for any new functions without test coverage.

Doc Refresh

Stale doc detection

Weekly cron: scan changed files, identify docs that are out of sync, open tickets via MCP.

Incident Response

CloudWatch → analysis

On alarm trigger, run your debugger agent against recent logs and post a structured incident summary to Slack.

🗂️

Nick's Agentic Playbook

Recipes tailored for your stack: Strands, Lambda, marketing advisor, MCP-connected workflows

Recipe 1: Ticket → Implementation → PR (zero manual steps)

Fetch ticket via MCP

→

Plan agent

→

Implementer agent

→

Review agent

→

Create PR via MCP

prompt to kick off full workflowFetch ticket MKTG-247 from Jira.
Analyze the requirements, create an implementation plan, then implement it.
When done, run tests and if they pass, open a PR with a summary of the changes
and a link back to the ticket.

Recipe 2: Strands Graph Debugging

debugging a plan graph node# With LSP initialized + aws-specialist agent active
The budget_optimizer node in our Strands plan graph is producing incorrect
recommendations for campaigns with ROAS > 4. Here's the failing test:

@tests/test_budget_optimizer.py

Use CloudWatch Logs to pull the last 5 Lambda invocations that triggered this
node and cross-reference with the node's input/output schema at @src/graph/nodes/budget_optimizer.py

Recipe 3: Observability Coverage Audit

observability gap analysisAudit @src/handlers/ for observability gaps:
1. Which handlers are missing OpenTelemetry span creation?
2. Which handlers aren't emitting EMF metrics for business events?
3. Which errors are caught but not logged with structured context?

Produce a prioritized list and create a ticket for each gap via our Jira MCP.

Recipe 4: ADR Generation

Given you've been working through architecture trade-offs, automate ADR creation:

adr workflowWe just decided to use Step Functions instead of Lambda for plan generation
because of the hard-kill timeout behavior we've been hitting.

Write an ADR in @docs/adr/ following the standard format. Include:
- Context (Lambda hard-kill, cold start, long-running graph issue)
- Decision
- Consequences (trade-offs per our steering file on architecture principles)
- Alternatives considered

Recipe 5: Steering File for Your Marketing Advisor

.kiro/steering/marketing-advisor.md (template)# Marketing Advisor Product Context

## Product
Conversational assistant + graph-based plan generation for ecommerce sellers.
Backend: AWS Lambda + Strands framework. MCP-connected marketing APIs.

## Architecture rules
- All LLM calls must include a correlation trace ID passed from the API gateway
- Lambda functions must flush OTEL spans before returning (ADOT layer pattern)
- Use EMF for business metrics, X-Ray for distributed tracing
- Plan generation graph nodes must be idempotent

## Seller data model
[key entities, IDs, relationships]

## Marketing API conventions
[request/response patterns, rate limits, error handling]

## What NOT to do
- Never suggest synchronous calls for plan generation (timeout risk)
- Don't use environment variables directly — always use SSM parameter store

The compounding flywheel: Every time you correct the agent or add context mid-conversation, ask yourself: should this be in a steering file? A few weeks of encoding your domain knowledge into steering files + well-configured agents will make every subsequent task 10x faster.

Max out Kiro CLI v2

The Upgrade Path

Power Combo: /editor + /agent swap

@path Inline Injection

Session Context Management

Knowledge Bases (in Custom Agents)

Multi-Session Picker

Global Steering (~/.kiro/steering/)

Workspace Steering (.kiro/steering/)

AGENTS.md Standard

Example: AWS/Lambda Specialist

Example: Code Review Agent

Agent Roster Strategy

Lifecycle Points

High-Value Hook Patterns

When to Use Subagents

Live Progress Tracking

Plan Agent (Built-in)

What You Unlock

Setup

TUI Mode (Graduated to Default in v2)

Setup

CI/CD Use Cases

Recipe 1: Ticket → Implementation → PR (zero manual steps)

Recipe 2: Strands Graph Debugging

Recipe 3: Observability Coverage Audit

Recipe 4: ADR Generation

Recipe 5: Steering File for Your Marketing Advisor