Revision · Learn Kiro

This page is generated from the same summary bullets that close each chapter, so it can’t drift out of sync with the content. Read it top to bottom (about ten minutes); any bullet that surprises you marks a chapter to revisit.

Best used: the day before an interview, right before the quizzes, or as re-entry after weeks away from Kiro.

Ch. 1

What is Kiro?

Start here

Kiro is Amazon's agentic AI development tool: it plans and performs multi-step coding work rather than offering single suggestions.
It lives in five places: the desktop IDE, the terminal CLI (kiro-cli), Kiro Web, an iOS app, and the open-source Kiro Crew.
Its signature idea is spec-driven development: requirements → design → tasks are written down before code is generated.
Steering files, hooks, MCP, skills, and powers let you shape, automate, and extend what the agent does.
Kiro differs from chatbots and autocomplete tools because it works inside your real project and takes reviewable actions.
It is powerful but not magic; you stay responsible for reviewing what it builds.

Ch. 2

History of Kiro

Start here

Kiro launched in public preview on July 14-15, 2025; demand was so high that AWS added a waitlist within weeks.
General availability came on November 17, 2025, adding Kiro CLI, property-based testing, checkpointing, and team plans.
December 2025 brought the autonomous agent and powers; 2026 brought IDE subagents, skills, Kiro Web, the Kiro IDE 1.0 release, an iOS app, OpenAI models, and cloud sessions on every surface.
August 2026 added a fifth surface: Kiro Crew, open-sourced under Apache 2.0 on August 4.
Kiro Web reached general availability on September 1, 2026, alongside cloud configuration sync and ISO 27001 coverage.
Kiro CLI is the evolution of Amazon Q Developer CLI: the q command still works and old configs migrate automatically.
Kiro changes monthly; the official changelog is the only reliable way to stay current.

Ch. 3

Kiro vs. Other AI Tools

Start here

These four tools embody four philosophies: the editor (Cursor), the platform (Copilot), the terminal agent (Claude Code), and the written plan (Kiro).
Cursor is an AI editor whose tab autocomplete is widely considered the best available, with no enforced planning step.
GitHub Copilot's strength is GitHub itself: agent mode in the editor, plus a coding agent you assign an issue to and that hands back a pull request.
Claude Code is a terminal-first agent on Claude models, with one subscription covering both Claude Code and the Claude apps.
Kiro is the only one of the four that makes a written, reviewable plan the default artifact, and it now spans five surfaces with Kiro Web generally available.
Choose by how your team already works, and re-check the official sites: all four ship significant changes monthly.

Ch. 4

Kiro vs Cursor

Comparisons

Cursor puts the AI in the editor; Kiro puts the plan in your repository as requirements.md, design.md, and tasks.md.
Cursor's tab autocomplete is widely considered the best in the category, and Kiro does not compete with it.
Kiro runs on five surfaces (IDE, CLI, Web, Mobile, Crew) and can run the agent in an AWS sandbox you attach to from any of them.
Kiro adds steering, hooks, powers, and skills as files your team reviews and commits; Cursor does not force a written planning step.
Both meter usage. Kiro sells credits from Free $0 to Power $200; Cursor had six plans from free to $200 when this was checked on 27 August 2026.
Running both is normal, and MCP setup carries across, so the choice is not a lock-in decision.

Ch. 5

Kiro vs Claude Code

Comparisons

Both are capable terminal agents. Kiro adds a written spec as the default path; Claude Code stays conversational.
Claude Code runs on Claude models only; Kiro offers Claude, OpenAI GPT-5.6, open-weight models, and an Auto router with per-model credit multipliers.
Kiro spans five surfaces and can move a session into an AWS sandbox that any surface attaches to; Claude Code is terminal-first with desktop, web, and IDE surfaces.
Kiro powers are not the same thing as skills: Kiro has skills too, on the open Agent Skills standard, plus powers that bundle MCP config with steering.
One Claude subscription ($20 to $200 when checked on 27 August 2026) covers Claude Code and the Claude apps; Kiro sells credits from Free $0 to Power $200.
Both speak MCP, so running both is practical and the switching cost is habits and configuration, not code.

Ch. 6

Kiro vs GitHub Copilot

Comparisons

Copilot's structural advantage is GitHub itself: assign an issue to the coding agent and get a pull request back.
Kiro's structural advantage is the written plan: requirements.md, design.md, and tasks.md exist before code does.
Copilot bills per seat and keeps code completions unlimited on paid plans, metering chat and agents in AI Credits at $0.01 each (checked 27 August 2026).
Kiro bills in credits from Free $0 to Power $200, with a per-model multiplier that changes what a task costs (checked 4 September 2026).
Kiro runs on five surfaces and supports GitHub and GitLab; Copilot is native to GitHub.
Both can be used together, and neither locks up your code, so pick on process fit rather than on a five-year bet.

Ch. 7

Kiro Alternatives

Comparisons

The three alternatives this site has verified are Cursor, Claude Code, and GitHub Copilot; each has its own comparison page.
Kiro has a genuine Free tier: $0 with 50 credits a month, open-weight models plus Claude Sonnet 4.5, but no Kiro Web.
Kiro Crew is open source under Apache 2.0, and the IDE is built on Code OSS; the shared agent harness is not documented as open source.
Kiro adopts open standards: MCP, the Agent Skills standard, the Agent Plugin format for powers, and the Agent Client Protocol.
Cursor and GitHub Copilot both had free plans when checked on 27 August 2026, so free entry points exist beyond Kiro.
People also compare Kiro with Cline, Google Antigravity, OpenCode, Augment Code, and Codex; this site has not reviewed any of them.

Ch. 8

Core Concepts

Core knowledge

Twelve ideas make up Kiro; every feature you meet is built from them.
Specs decide what gets built, steering shapes how the agent thinks, hooks decide when it acts, MCP and powers extend what it can reach.
Custom agents and skills package who the agent is and what procedures it knows.
Five surfaces (IDE, CLI, Web, mobile, Crew) run the same agent harness, and cloud sessions decide whose machine it runs on.
Permissions rank deny over ask over allow; checkpoints undo agent file edits; compaction summarizes old history; .kiroignore keeps paths out of reach.
Surface support differs feature by feature, so check the matrix before planning a workflow around one.

Ch. 9

Kiro Crew

Core knowledge

Kiro Crew is an open-source personal AI agent (Apache 2.0, open-sourced August 4, 2026) that runs locally or remotely on your own hardware.
It is the persistent layer beside the IDE, CLI, Web, and mobile: always on, rather than session-shaped.
Install as a desktop app, with a curl one-liner, with pip install kirocrew, or from the Docker image.
Three commands get you started: kirocrew setup, kirocrew doctor, kirocrew gateway on port 5476.
Features include subagents, scheduling, artifacts, a task runner, memory, knowledge, snapshots, browser automation, and workflows.
The security model has an owner lock, 137 denied command patterns, three sandbox modes, output redaction, and a signed audit log.
Model calls go through kiro-cli, so Kiro credits apply; the docs list no separate Crew price.

Ch. 10

Choosing a Model

Core knowledge

Every model carries a credit multiplier measured against Auto, which is 1.0x and the default.
The spread is enormous: Opus 5 is 2.2x and GPT-5.6 Sol is 2.4x, while Qwen3 Coder Next is 0.05x.
Auto is a router: it picks a model per request instead of making you decide every time.
Sonnet 5 (1M context, 1.3x) is the sensible daily driver; Opus 5 is for the genuinely hard work.
Haiku 4.5 (0.4x) and the open-weight models exist for mechanical, high-volume tasks.
The Free tier gets only Sonnet 4.5 plus open-weight models, and the lineup changes monthly.
Reasoning effort (low, medium, high, xhigh, max) is a second dial: lower effort is faster, shorter, and cheaper.

Ch. 11

Credits & Pricing

Core knowledge

Kiro bills in credits: Free $0/50, Pro $20/1,000, Pro+ $40/2,000, Pro Max $100/5,000, Power $200/10,000 per user per month.
A credit is a unit of agent work, billed fractionally in 0.01 steps; simple asks cost under 1 credit, executing a spec task costs more.
Every request draws from one unified credit pool (since October 2025); billable work is agentic requests, not inline autocomplete.
Model choice is the biggest lever: the same task costs 2.2x more on Opus 5 than on Auto, and 0.4x on Haiku 4.5.
Credits do not roll over, and overage at $0.04/credit is exactly double the $0.02/credit every paid tier charges.
Free tier is Sonnet 4.5 plus open-weight models only; premium models and Kiro Web need a paid plan.
Kiro Web has been generally available on the paid plans since September 1, 2026, drawing from the same credit pool as the IDE and CLI.

Ch. 12

Agentic Development

Concepts

Agentic development means the AI plans steps, edits files, runs commands, checks results, and adjusts, instead of only replying with text.
Kiro runs one agent harness behind every surface, so the IDE, CLI, Web, mobile, and Crew all behave the same way.
Each turn follows the same loop: assemble context, plan, check permissions, run tools, feed results back, manage context.
Autopilot works end to end; Supervised pauses after each turn that edits files, set by kiroAgent.agentAutonomy in the IDE.
Checkpoints snapshot the files the agent changed with its built-in tools, so you can restore a bad run.
Your job shifts from typing every line to writing precise intent and reviewing the result.

Ch. 13

Specs

Concepts

A spec is a written plan Kiro builds with you: requirements.md, design.md, and tasks.md, stored in .kiro/specs/ inside your repository.
Requirements use EARS notation: WHEN for normal behavior, IF/THEN for errors, WHILE for ongoing states.
Feature specs offer Requirements-First, Design-First, and Quick Plan workflows; bugfix specs replace requirements.md with bugfix.md.
An optional requirements analysis flags ambiguity, contradictions, and gaps before any code is written.
Independent tasks execute concurrently in waves, and property-based testing checks that the code matches the spec.
Use specs for complex features, risky bug fixes, and work teammates must understand later; use plain chat for exploration.

Ch. 14

Steering

Concepts

Steering files are Markdown documents that give Kiro persistent knowledge about your project, so you stop re-explaining your stack every session.
Three foundational files are included by default: product.md, tech.md, and structure.md.
Workspace steering lives in .kiro/steering/ and global steering in ~/.kiro/steering/; the two scopes merge.
Inclusion modes in YAML front matter control when a file loads: always, fileMatch, manual, or auto.
AGENTS.md files also load as steering, from anywhere in the workspace tree, and are always included.
One domain per file, always explain the why, and never put secrets in a steering file.

Ch. 15

Hooks

Concepts

A hook is an automation: when X happens, run an agent prompt or a shell command.
Triggers include file save, create, and delete, prompt submission, agent turn complete, before and after tool invocation, before and after spec tasks, and manual buttons.
Hooks live in .kiro/hooks/ for a project and ~/.kiro/hooks/ globally, and the two scopes merge.
You create them in natural language or through a guided form in the IDE.
Scope triggers narrowly and keep hook actions small, or the automation becomes the slowest part of your day.
A hook that edits files can trigger itself, which is the classic hook bug.

Ch. 16

MCP

Concepts

MCP is the open protocol Kiro uses to reach tools and data outside your codebase.
Servers are configured in .kiro/settings/mcp.json for a project and ~/.kiro/settings/mcp.json globally.
Precedence runs agent, then project, then global: the closer scope wins.
Local servers use command, args, and env with ${VAR} expansion; remote servers use url, headers, and oauth.
autoApprove lets the agent call tools without asking, which is fine for read-only servers and risky for anything that writes.
The MCP servers panel and the Kiro - MCP Logs output channel are the first place to look when a server misbehaves.

Ch. 17

Custom Agents

Concepts

A custom agent is a scoped version of Kiro: its own instructions, allowed tools, resources, and model.
The CLI defines agents as JSON and the IDE as Markdown with YAML front matter; both live in .kiro/agents/ or ~/.kiro/agents/.
The tools field takes categories: read, write, shell, web, and @builtin for the whole built-in set.
A project agent supersedes a global one with the same name, and Kiro warns about the collision.
Restricting tools is the point: an agent that cannot write files can be trusted to run freely.
Create with /agent create, switch with /agent swap, or start directly with kiro-cli --agent <name>.

Ch. 18

Skills

Concepts

A skill is a reusable instruction pack: a folder with a SKILL.md file, plus optional scripts and templates.
SKILL.md has YAML front matter with a name and a description, followed by the procedure itself.
Kiro reads only names and descriptions at session start, then loads the full skill when a request matches or you invoke it as a slash command.
Workspace skills live in .kiro/skills/ and personal skills in ~/.kiro/skills/; the scopes merge.
Kiro follows the open Agent Skills standard, so skills are portable across tools that support it.
The description is the whole activation mechanism, so vague descriptions produce skills that never fire.

Ch. 19

Powers

Concepts

A power is a one-click bundle that makes the agent good at a specific technology.
Inside: a POWER.md steering file, an MCP server configuration, and optionally extra steering or hooks.
Powers load on demand when the conversation matches, instead of adding always-on MCP tools to every session.
Launch partners in December 2025 included Stripe, Supabase, Figma, Neon, Netlify, Datadog, Dynatrace, and Postman.
Since IDE v1.0.288 in August 2026, powers are packaged in the open Agent Plugin format and install from local folders or GitHub URLs.
A power configures instructions and tools for your agent, so read one before you install it.

Ch. 20

Cloud Sessions

Concepts

A cloud session runs the Kiro agent in a managed AWS sandbox instead of on your machine.
All four surfaces create and attach to the same sessions: IDE v1.0.293+, CLI v2.17+, Web, and the iOS app.
In the CLI, kiro-cli --cloud starts one, --repo or /repo attaches a repository, and --resume-id reattaches from any machine.
Project configuration travels with the repository; personal ~/.kiro/ settings stay local unless synced through Web settings.
Documented limits: a paid plan, US East (N. Virginia), at most 10 concurrent sessions, no Supervised mode, no renaming.
Cloud runs keep spending credits after you close the laptop, so end them deliberately.

Ch. 21

Kiro IDE

Concepts

The Kiro IDE is a desktop editor built on Code OSS, the open-source core of VS Code, with the agent woven in.
Platform support: macOS Intel and Apple silicon, Windows 10 and 11 64-bit with no ARM, Linux with glibc 2.39 or newer.
Agent Autonomy (kiroAgent.agentAutonomy) selects Autopilot, which works end to end, or Supervised, which pauses for hunk-by-hunk approval.
Checkpoints are created on every prompt and restore the files the agent changed with its built-in tools.
The # context providers (#file, #folder, #codebase, #terminal, #problems, #git diff) beat pasting code into chat.
Since v1.0.395 third-party extensions work alongside Kiro; v1.0.437 added cloud configuration previews.

Ch. 22

Kiro CLI

Concepts

kiro-cli runs the same agent in your terminal, and it is the surface that works over SSH, in containers, and in CI.
Windows support is narrower than the IDE's: Windows 11 only, installed from PowerShell, not Command Prompt.
Slash commands steer a session: /context, /chat, /agent, /spec, /compact, /effort, /tangent, /mcp.
Headless mode runs one prompt non-interactively with KIRO_API_KEY and trusted tool categories, which is how Kiro fits into CI.
kiro-cli acp speaks JSON-RPC 2.0 over stdin and stdout, so JetBrains and Zed can use Kiro as their agent.
v2.20.0 added a full-screen spec task view; v2.21.0 added a session dashboard and a configuration panel.

Ch. 23

Kiro Web

Concepts

Kiro Web at app.kiro.dev runs the agent against GitHub and GitLab repositories with nothing installed locally.
It reached general availability on September 1, 2026, on Pro, Pro+, Pro Max, and Power, and is not on the Free plan.
Autonomous mode runs clarification, planning, and sandboxed execution by sub-agents, and delivers a pull request.
Automations schedule autonomous runs hourly, daily, or on CRON, up to five schedules each, with the output as a PR.
Memory learns from the task creator's PR feedback and is viewable and deletable per user under Settings.
Cloud configuration sync pushes Web-defined agents, MCP servers, powers, steering, skills, and hooks down to local sessions.

Ch. 24

Beginner Tutorial

Hands-on

Install from kiro.dev (macOS, Windows 10/11 64-bit, modern Linux); sign in with Google, GitHub, AWS Builder ID, or SSO.
Start in Supervised mode so every change waits for your approval while you learn.
Use # context providers (#file, #codebase) instead of pasting code into chat.
Your first spec turns a one-line idea into requirements.md, design.md, and tasks.md that you approve before code.
A small steering file makes the agent remember your project's basics across sessions.
You can complete this entire tutorial on Kiro's free tier, no credit card needed.

Ch. 25

Advanced Tutorial

Hands-on

Lay foundations first: product.md, tech.md, structure.md in .kiro/steering/, then narrow fileMatch rules.
Run features as requirements-first specs; use requirements analysis to catch ambiguity before design.
Run regressions as bugfix specs: analysis in bugfix.md, regression test before the fix.
Hooks automate the boring loop (tests, doc sync); scope triggers narrowly to avoid noise and loops.
Configure MCP per workspace with empty autoApprove by default; approve tools deliberately.
Use restricted custom agents for roles (read-only reviewer); share team know-how as skills in .kiro/skills/.

Ch. 26

Kiro CLI Guide

Hands-on

Install: curl -fsSL https://cli.kiro.dev/install | bash on macOS/Linux; irm 'https://cli.kiro.dev/install.ps1' | iex in PowerShell on Windows 11.
kiro-cli starts a chat; kiro-cli --agent <name> starts as a specific persona.
/context add|show|remove|clear controls what the agent sees; ! prefixes direct shell commands.
/chat new|save|load and the --resume flags make sessions persistent and shareable.
Custom agents, steering, hooks, MCP, and skills all work in the CLI. It is not a lite version.
Headless mode with API keys enables CI/CD automation.
Permissions, checkpoints, compaction, .kiroignore, and configuration scopes all apply in the terminal.

Ch. 27

Use Cases

Hands-on

New app or big feature: start a spec (requirements.md → design.md → tasks.md); keep vibe chat for throwaway exploration.
Risky refactors: steering pins your conventions, supervised mode reviews changes hunk by hunk, checkpoints give you a way back.
Docs and tests stay fresh with hooks that fire on file save; property-based testing checks the implementation against your spec.
Debugging: bugfix specs put the root-cause analysis in bugfix.md; #problems and #terminal feed real errors to the agent without copy-paste.
Code review: a read-only custom agent makes a strict reviewer; Kiro 0.9 added granular code review in the IDE.
Data work: steering encodes warehouse conventions and metric definitions, MCP connects your data tools, and the CLI runs on remote machines.
Advanced: the Kiro CLI runs headless in CI/CD with API-key auth. Restrict its tools and gate its output behind normal review.

Ch. 28

Kiro for Data Engineers

Hands-on

Data mistakes fail quietly: a wrong join produces plausible numbers, not an error, so a written spec is worth more here than almost anywhere else.
Steering encodes your SQL style, layer naming, partitioning rules, and metric definitions once, so generated models land in house style.
MCP connects the agent to a database so it reads real schemas instead of guessing column names; approve read-only tools only.
A .kiroignore keeps data dumps, exports, and credential files out of the agent's reach, with full support in the IDE.
The CLI works over SSH on training boxes and remote servers, and runs headless in CI for scheduled data chores.
Pick a low-multiplier model for bulk work like backfilling docstrings; the multiplier changes your bill more than your plan does.

Ch. 29

Migrate from Amazon Q Developer

Hands-on

Kiro CLI succeeded Amazon Q Developer CLI on 17 November 2025; the q entry points still work and config moved from ~/.aws/amazonq to ~/.kiro.
New Q Developer signups closed on 15 May 2026, and IDE plugins and paid subscriptions reach end of support on 30 April 2027.
Everything Q Developer did (inline suggestions, chat, code generation) exists in Kiro; Kiro adds specs, steering, hooks, custom agents, skills, powers, and a command allow/deny list.
VS Code users install the Kiro IDE and accept the profile import prompt; sign-in is GitHub, Google, AWS Builder ID, or IAM Identity Center.
JetBrains users install Kiro CLI and add it as a custom agent through ACP; Visual Studio and Eclipse have no plugin, so use the Kiro IDE or CLI alongside.
Budget time for the new concepts, not the install: the migration is quick, but steering and specs change how you work.

Ch. 30

Recipes

A recipe is one task in one page: when to use it, the steps, how to check it worked, and the usual problems.
Setup recipes cover steering, AGENTS.md, hooks, MCP servers, Powers, agents, and skills.
Safety recipes cover permissions.yaml, .kiroignore, checkpoints and rewind, and compaction.
Automation recipes cover headless CI, Web automations, cloud sessions, and running Kiro Crew 24/7.
Every command and file path in a recipe is verified against the official docs; anything not verified is described in prose and linked to the docs.

Ch. 31

Create Your First Steering File

Recipes

Steering files are Markdown notes in .kiro/steering/ that the agent reads before it answers.
product.md, tech.md, and structure.md are the foundational files and load by default.
YAML front matter must be the first content in the file; inclusion: always is the default.
inclusion: fileMatch plus fileMatchPattern loads a file only for matching paths.
Global files live in ~/.kiro/steering/; the workspace copy wins when the two conflict.

Ch. 32

Use AGENTS.md as Steering

Recipes

Kiro loads AGENTS.md as steering context, from the workspace root and from subdirectories.
Support arrived in CLI v2.18.0 and IDE v1.0.309, both in August 2026.
AGENTS.md files do not support inclusion modes; they are always included.
They load alongside your .kiro/steering/ files rather than replacing them.
Use AGENTS.md for rules every tool should read; use .kiro/steering/ when you need fileMatch.

Ch. 33

Run Tests on Save With a Hook

Recipes

Hooks are automated triggers that run an agent prompt or a shell command on an event.
File save, file create, file delete, prompt submission, agent turn complete, tool calls, and spec tasks can all trigger a hook.
Create hooks from the Kiro panel with natural language or the guided form, not by hand-writing config.
Project hooks live in .kiro/hooks/; global hooks live in ~/.kiro/hooks/ and apply to every workspace.
Scope the file pattern to one area and keep the action light, or the team will turn hooks off.

Ch. 34

Keep Docs in Sync With a Hook

Recipes

A documentation hook watches source files and asks the agent to check the matching docs.
Trigger on file save for a narrow source folder, and write output only to the docs folder.
The IDE can also trigger hooks on agent-driven file changes, not only on your own saves.
Ask the hook to propose a diff for review rather than commit changes silently.
Project hooks live in .kiro/hooks/; global hooks live in ~/.kiro/hooks/.

Ch. 35

Add an MCP Server

Recipes

Workspace MCP config lives in .kiro/settings/mcp.json; personal config lives in ~/.kiro/settings/mcp.json.
Precedence runs agent over project over global, so the closest scope wins.
Local servers use command, args, and env; remote servers use url with headers or oauth.
Start every server with autoApprove set to an empty list, then approve read-only tools you actually use.
MCP calls are permission-checked under the mcp capability, and --require-mcp-startup fails a headless run fast.

Ch. 36

Add a Power

Recipes

A Power bundles POWER.md, MCP server configuration, and optional steering and hooks.
Powers load on demand when your request matches, which keeps default context smaller than always-on MCP.
Installed Powers live in ~/.kiro/powers/.
Since IDE v1.0.288 Powers use the open Agent Plugin format, installable from a local folder or a GitHub URL.
Cloud-synced Powers appear in the installed list as read-only previews; edit them in Kiro Web.

Ch. 37

Create a Custom Agent

Recipes

IDE custom agents are Markdown files in .kiro/agents/ (project) or ~/.kiro/agents/ (global).
YAML front matter carries description, model, tools, mcpServers, and permissions; the body is the system prompt.
The tools field takes the categories read, write, shell, web, and @builtin.
A project agent supersedes a global agent with the same name, and Kiro warns about the clash.
In the CLI use /agent create to make one, /agent swap to switch, and kiro-cli --agent <name> to start as one.

Ch. 38

Build a Read-Only Reviewer Agent

Recipes

A reviewer agent lists only the read tool category, so it cannot write files or run commands.
Deny rules in permissions.yaml enforce the ceiling, because deny beats ask and allow in every scope.
A hard ceiling is what makes it safe to run a review agent in Autopilot.
Give the agent your standards document so its review has a reference, not just an opinion.
Ask for findings, never fixes; a reviewer that edits is an implementer with a misleading name.

Ch. 39

Write a Skill

Recipes

A skill is a folder with a SKILL.md file that has YAML front matter carrying a name and a description.
Workspace skills live in .kiro/skills/; personal skills live in ~/.kiro/skills/, and the two merge.
Kiro discovers skills at session start by name and description, then loads the body when it is needed.
A skill activates when a request matches its description, or explicitly as /skill-name.
The description is the trigger, so write it about the situation, not about the skill.

Ch. 40

Fix a Bug With a Bugfix Spec

Recipes

A bugfix spec is a spec variant whose analysis document is bugfix.md instead of requirements.md.
It still produces design.md and tasks.md, so the fix is reviewed before any code changes.
Specs live in .kiro/specs/, one folder per spec, committed with the repository.
Make the first task a failing regression test, and the fix the second task.
Use a bugfix spec for risky or recurring bugs; a one-line typo does not need one.

Ch. 41

Run Kiro CLI Headless in CI

Recipes

kiro-cli chat --no-interactive "prompt" takes the prompt as an argument and exits when done.
Authentication in headless mode comes from the KIRO_API_KEY environment variable.
--trust-tools=<categories> pre-approves only the categories you name; --trust-all-tools exists and deserves suspicion.
--require-mcp-startup fails the run fast instead of hanging when an MCP server cannot connect.
Run headless jobs as a restricted custom agent and watch the credit spend, because nobody is watching the loop.

Ch. 42

Set Up permissions.yaml

Recipes

User rules live in ~/.kiro/settings/permissions.yaml; workspace rules live under ~/.kiro/workspace-roots/<hash>/permissions.yaml, outside the repository.
Capabilities include fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, and sandbox_network.
Meta capabilities all, builtin, and filesystem cover groups at once.
Effects rank deny over ask over allow, and deny wins regardless of scope.
Rules take a match glob and an optional exclude glob; six scopes run from Kiro's hardcoded rules down to the session.

Ch. 43

Keep Secrets Out With .kiroignore

Recipes

A .kiroignore file uses gitignore syntax and can sit in the workspace root or in subdirectories.
Global rules live in ~/.kiro/settings/kiroignore and apply to every project.
The IDE setting kiroAgent.agentIgnoreFiles adds patterns from the settings UI.
Support differs by surface: full in the IDE, search results only in CLI V3, not yet in Web or Mobile.
Negation works, but you cannot re-include a file inside a directory you excluded.

Ch. 44

Undo With Checkpoints and Rewind

Recipes

Kiro creates a checkpoint automatically on every prompt and snapshots the files the agent changed with its built-in tools.
Restoring a checkpoint puts those files and the agent context back, and discards the later chat.
Checkpoints are supported in the IDE and are experimental in CLI V3; Web and Mobile do not have them.
Rewind is CLI only: it forks the conversation at an earlier turn into a new session and leaves files untouched.
Manual edits, formatter runs, MCP tool writes, and shell commands are not tracked, so git stays your real safety net.

Ch. 45

Compact a Long Session

Recipes

Compaction summarises older history when the context fills; it runs automatically in the IDE, CLI, Web, and Mobile.
Manual /compact exists in the CLI only.
It keeps task status, file paths, decisions, and next steps; it summarises tool output, old code snippets, and resolved errors.
Compaction is one-way: history before the compaction point cannot be recovered.
compaction.excludeMessages and compaction.excludeContextWindowPercent protect recent turns, and the more conservative of the two wins.

Ch. 46

Set the Reasoning Effort

Recipes

The levels are low, medium, high, xhigh, and max.
Opus 5, Opus 4.8, and Sonnet 5 support all five; Opus 4.7, Opus 4.6, and Sonnet 4.6 have no xhigh.
GPT-5.6 Terra, Sol, and Luna support all levels and default to high.
In the IDE, click the model name in the chat input and use the effort panel. In the CLI, use /effort or --effort.
Defaults live in chat.modelDefaults in ~/.kiro/settings/cli.json or .kiro/settings/cli.json; session beats workspace beats user beats built-in.

Ch. 47

Use Kiro CLI in JetBrains or Zed

Recipes

kiro-cli acp speaks JSON-RPC 2.0 over stdin and stdout, which is what ACP clients expect.
Add --agent to start the ACP process as a specific custom agent.
JetBrains reads ~/.jetbrains/acp.json; Zed reads ~/.config/zed/settings.json under a Kiro Agent entry.
Use the full path from which kiro-cli, because the editor may not inherit your shell PATH.
CLI sessions are stored in ~/.kiro/sessions/cli/.

Ch. 48

Schedule a Web Automation

Recipes

Automations are a Kiro Web feature on paid plans, Pro and above.
Schedules can be hourly, daily, or CRON, up to five per automation, and all times are UTC.
The prompt can be up to 10,000 characters and can target one or more repositories.
Automations run in autonomous mode and the output is a pull request for you to review.
Kiro's documentation warns to select only repositories you trust, because the agent follows instructions found in repository code.

Ch. 49

Start a Cloud Session From the CLI

Recipes

kiro-cli --cloud runs the agent in a managed sandbox instead of on your machine; it arrived in CLI v2.17.0.
Attach a repository with --repo or the /repo picker; the repository is fixed when the session is created.
Reattach from any machine with kiro-cli chat --resume-id <id>.
Cloud sessions need a paid plan, run in US East (N. Virginia) during preview, and cap at 10 running at once.
Enterprise administrators must enable cloud sessions, because they ship opt-in for organisations.

Ch. 50

Run Kiro Crew 24/7

Recipes

Install Crew from the desktop app, a one-line script, pip, or the ghcr.io/kirodotdev/kirocrew Docker image.
kirocrew setup runs the wizard, kirocrew doctor verifies the install, and kirocrew gateway starts the server on port 5476.
kirocrew service install registers systemd on Linux or launchd on macOS so Crew survives reboots.
A remote host needs Linux, about 10 GB RAM minimum and 16 GB recommended; the dashboard binds to loopback only.
Reach a remote dashboard with an SSH tunnel, and never sync .env, .local_secret, or sel_hmac.key between machines.

Ch. 51

Change the Default Model

Recipes

In the IDE, click the model name in the chat input to open the model and effort panel.
Auto is a router, not a model: it picks a frontier model automatically and never routes to experimental ones.
Auto uses Sonnet-class or better on Free, and Opus-class or better on paid plans.
Kiro CLI keeps persistent model preferences, added in v2.6.0.
chat.modelDefaults in ~/.kiro/settings/cli.json or .kiro/settings/cli.json sets effort defaults per scope.

Ch. 52

The Workspace Game

Practice

Round 1 drills tool choice across all eleven core concepts: steering, hooks, MCP, specs, custom agents, skills, powers, checkpoints, context providers, and the three surfaces.
Round 2 drills anatomy: .kiro/steering/, .kiro/settings/mcp.json, .kiro/agents/, SKILL.md structure, front-matter placement, spotting secrets and autoApprove risks in real configs.
Round 3 drills fluency: EARS lines, inclusion modes, spec and skill workflows in sequence, headless kiro-cli, and judgment calls like reviewing cloud-agent pull requests.
Every wrong answer explains why that exact option fails, misses return in a repair round, and a per-concept mastery map accumulates across runs to tell you what to reread.

Ch. 53

Practice Exercises

Practice

Nine exercises ladder from first conversation to a team-ready, automated data pipeline setup.
Beginner: chat + context, first spec, first steering file. Intermediate: hooks, MCP, CLI sessions. Advanced: restricted agents, bugfix specs, full pipelines.
Each exercise defines the objective, a realistic scenario, checkable tasks, an observable outcome, hints, and an optional challenge.
Do them in order; each level assumes the muscle memory of the previous one.

Ch. 54

Quizzes

Practice

The beginner quiz covers what Kiro is, the three surfaces, spec files, steering, hooks, MCP, and modes.
The advanced quiz covers EARS patterns, inclusion modes, MCP precedence, custom agents, skills vs powers, and CLI workflows.
Multiple-choice questions give instant feedback; short-answer and scenario questions have model answers to compare against.
Every quiz ends with a complete answer key with explanations.

Ch. 55

Cheat Sheet

Reference

All Kiro state lives under .kiro/ (workspace) and ~/.kiro/ (global): steering, settings, agents, skills, hooks.
Spec = requirements.md + design.md + tasks.md; bugfix specs use bugfix.md.
EARS: WHEN for normal behavior, IF/THEN for errors, WHILE for ongoing states.
CLI: kiro-cli to start; /context, /chat, /agent are the three command families that matter.
Permission effects rank deny over ask over allow, and deny wins from any scope.
Five surfaces: IDE, CLI, Web (GA on paid plans), iOS, and Kiro Crew on your own hardware.

Ch. 56

Troubleshooting & FAQ

Reference

Update first. A surprising share of known symptoms have a fix date attached to a specific IDE or CLI version.
The CLI's requirements are narrower than the IDE's: Windows 11 only, PowerShell not Command Prompt, glibc 2.34+ on Linux.
Sign-in trouble is usually one of three things: no browser on the machine, a corporate proxy, or a different identity provider than last time.
For MCP, read the servers panel and the Kiro - MCP Logs output channel before touching any config file.
Context-limit errors start with /context show; workspace mcp.json quietly overrides the user-level one.
kiro.dev/changelog is the referee for any behavior that disagrees with this page.

Ch. 57

Common Mistakes & Don'ts

Reference

Vague prompts produce confident, wrong output. Precision in, quality out.
Never accept diffs unread; in early days, stay in Supervised mode.
Trust generated code least exactly where bugs cost most: security, money, concurrency, data deletion.
Commit before agent sessions and keep agent work on branches. Git is your real undo button.
Keep secrets out of steering and chat; treat autoApprove and third-party powers like production access.
Automate gradually: a noisy hook or an unwatched headless job is worse than no automation.
The newer features have their own traps: Autopilot without deny rules, Web Automations on untrusted repositories, Crew with the sandbox off, and host secrets synced to a remote Crew.

Ch. 58

Interview Questions

Reference

Eight beginner questions cover definitions: what Kiro is, the surfaces, spec files, steering, modes, MCP, and the .kiro folder.
Six workflow questions test daily judgment: spec vs vibe, team steering, hooks, reviewing output, checkpoints, and context providers.
Six advanced questions go deeper: EARS, custom agents, skills vs steering vs powers, MCP config precedence, task waves, and headless CI.
Five questions each target data engineering and software engineering scenarios, where Kiro features map to real job duties.
Six current-events questions cover Kiro Web general availability, Kiro Crew, permissions, compaction, checkpoints and rewind, and configuration scopes.
Prepare by answering each question aloud before reading the model answer: recall beats recognition.

Ch. 59

Glossary

Reference

Sixty-plus Kiro terms in alphabetical order, each in one or two sentences with a link to the full explanation.
Covers the building blocks: specs, steering, hooks, MCP, custom agents, skills, powers, and Crew.
Covers the safety vocabulary: permissions, capabilities, sandbox modes, .kiroignore, checkpoints, and rewind.
Covers the money vocabulary: credits, multipliers, reasoning effort, and the Auto router.
Use it as a lookup table, not a chapter to read end to end.

Related chapters