How Kiro works

Kiro is one agent, available everywhere you work. Close your laptop and your session keeps running in the cloud. Check on it from your phone. Pick it up in the IDE the next morning. The IDE, CLI, Web, and Mobile apps are different ways to talk to the same unified agent harness, so when you configure a steering rule, write a custom agent, or connect an MCP server, you're configuring Kiro itself, not one particular app.

That one idea organizes everything else: capabilities live at the Kiro level and are documented once in Features, while each surface section covers only what that surface adds on top. This page walks through how the pieces fit together. For the engineering story behind the architecture, read One agent, every surface on the Kiro blog.

At the center is the unified agent harness, which handles everything an agent run involves: orchestrating the conversation, executing tools, managing context, evaluating permissions, and talking to the LLM providers. Every Kiro surface (the IDE, CLI, Web, and Mobile) is a front end to that same harness.

The harness is a standalone process, not a library compiled into each app. It runs alongside your codebase, owns everything on the agent side, and the client owns how you interact with it. Because it's a separate process, the same harness can start on your laptop or inside a cloud sandbox, and it behaves identically in both.

Because the harness is shared, a capability behaves the same wherever it's available. A permission rule denies the same operations in the CLI as in the IDE. A steering file shapes the agent's behavior identically on every surface. Compaction preserves the same information. The surfaces differ in how you drive the agent, not in what the agent can do. Where a capability hasn't reached a surface yet, its feature page says so up front in an availability table.

Clients talk to the harness through the open Agent Client Protocol (ACP). That includes Kiro's own surfaces: the IDE, CLI, Web, and Mobile apps all speak ACP, extended with Kiro-specific methods (under the spec's _kiro/ namespace) for features like live steering, spec workflows, rich permission prompts, and context usage tracking. Local clients connect over stdio; Web and Mobile connect to a sandboxed harness over WebSocket. Same binary, same tools, same behavior on either transport.

When you send a prompt from any surface, the harness runs the same loop:

1. Context is assembled. The harness gathers your prompt, the conversation so far, your steering files, and anything you attached. Prompt Submit hooks run here and can inject context of their own.
2. The model plans. The request goes to your selected model, or Auto routes it to the best one for the task, and comes back with text, tool calls, or both.
3. Every tool call is checked. Before a tool runs, permission rules are evaluated (deny overrides ask, ask overrides allow), along with kiroignore patterns where they're enabled. Pre Tool Use hooks can gate or block the call.
4. Tools execute. Built-in tools read and edit files, run shell commands, and search the web. MCP servers and Powers extend the set, and sub-agents take on delegated work. Post Tool Use hooks react to the results.
5. Results feed back. Tool output returns to the model, and the loop repeats until the task is done. Agent Stop hooks fire when the turn completes.
6. Context stays managed. As the conversation approaches the model's context limit, compaction summarizes older history so the session keeps going.

This loop is why the Features section is organized the way it is: each capability is a stage of the loop, not a bolt-on in one app. A permission rule you write once gates step 3 everywhere. A steering file shapes step 1 everywhere. That's the practical meaning of "one harness."

Each harness capability is documented once, at the Kiro level:

You'll find these under Features in the sidebar (Models has its own section). Not every capability has reached every surface yet, so each page opens with an availability table showing exactly where it works today. The direction is one harness, everywhere.

The loop is the same everywhere, but the computer it runs on differs by surface:

• IDE and CLI run the harness on your machine. Tools operate on your local filesystem, shell commands run in your shell, and builds use your locally installed toolchain and credentials.
• Web and Mobile run the same harness in a managed cloud sandbox. Kiro clones your connected repository into an isolated environment, works there, and delivers changes back as pull requests. Nothing executes on your machine, and sessions keep running after you close your laptop. Mobile picks up the same cloud sessions, so you can start work in the browser and check in from your phone.

Same loop, same rules, same configuration format. The difference is where the work happens and how the results reach you.

The surface sections document the experience around the agent: how you invoke it, see its work, and stay in control. Surfaces aren't thin wrappers, either. A client can provide its own tools in place of the harness's built-ins where its platform does the job better; the IDE, for example, uses the editor's own APIs for file operations and adds editor-native code analysis on top.

If you're reading a surface section and find yourself asking "but how does the feature itself work?", the answer lives in Features, one level up.

Configuration follows the same shared model. What you define once applies wherever the harness runs:

This is why Kiro Web and Mobile can pick up your project's agents and steering with no setup: they read the same .kiro/ directory from your repository that the IDE and CLI use locally. See Configuration scopes for the complete reference.

• Learn once, use everywhere. The permissions.yaml you write for the CLI is the same file the IDE consults. A skill you add to your project works from every surface that opens it.
• Consistent upgrades. Harness improvements land in one place, and changes that don't touch the client protocol reach every surface with no app updates needed. Global hooks in ~/.kiro/hooks/ and improved compaction both shipped this way, arriving on all surfaces at once.
• Team-wide consistency. Committing .kiro/ to your repository gives everyone the same agent behavior, whether they prefer the IDE, the terminal, or the browser.

• Configuration scopes for where every setting lives and how conflicts resolve
• Custom agents to shape the agent's tools, permissions, and prompt
• Permissions to control what the agent can do
• Getting started to install Kiro on your surface of choice