Kiro, Then and Now — Three Engines Converging into One
Kiro's IDE, CLI, and web began with separate agent engines and are now merging into one harness over ACP. The IDE and web have moved; the CLI is due in 3.0.
Why did the same .kiro/ folder get read differently?
Kiro is an AI coding tool built by AWS. It comes in several forms — a desktop IDE, a CLI for the terminal, a web app in the browser, and a phone app. Kiro calls each of these a "surface." Whichever surface you use, you keep files such as agent configurations, hooks (actions that run automatically at set moments), and steering (instructions for the agent) in the
.kiro/ folder at the project root.I've been using an open-source development methodology called AI-DLC (awslabs/aidlc-workflows ) with Kiro, and I often looked through its configuration files. Something about them puzzled me for a long time: it was all Kiro, yet the IDE and the CLI needed separate configuration files. In the public AI-DLC v2.7.0 release (September 2026), the IDE folder holds hook files with the same names in two formats side by side. One is a
.kiro.hook file that the old IDE reads; the other is a .kiro/hooks/*.json file that the new IDE reads. In the CLI folder, the hooks live inside the agent configuration files themselves.At first I assumed the configuration syntax of one program had simply drifted a little from version to version. A post the Kiro team published in August 2026 changed my mind. The difference wasn't syntax. Each surface ran a completely different agent engine.
This post is based on the Kiro team's public posts and documentation, plus tests I ran on a Mac.
Then: a separate harness for each surface
The Kiro team calls the layer that drives the agent the harness. Their definition: the orchestration layer that manages the agent loop, tool execution, sub-agent delegation, session management, configuration loading, and communication with the model. It's the part behind the user-facing interface that actually does the work of an "agent."
According to the Kiro team's post "One agent, every surface" (August 3, 2026), they initially optimized for speed and experimentation and had each client team build its own harness.
The IDE team built theirs in TypeScript to fit the Code OSS extension model, the CLI team built theirs in Rust for performance, and the web team built theirs in Python to stay close to the latest agent research.
So the IDE was TypeScript, the CLI was Rust, and the web client was Python. They shared the Kiro name, but underneath they were three programs written in three languages. That let each team ship quickly, but each team also made its own choices. Spec-driven development, which appears in the table below, is Kiro's signature feature: you work through requirements, a technical design, and a task list together with the agent. Powers bundle the tools and practices for a particular technology and load them for the agent when needed. Here is where the surfaces diverged, as the same post describes it.
| What diverged | IDE (0.x) | CLI (old engine, 1.x and 2.x) |
|---|---|---|
| Terminal command permissions | Prefix matching for trustedCommands, plus substring matching for the denylist | Regex matching with allowedCommands and deniedCommands |
| Session storage | Its own | Its own |
| Compaction strategy for long conversations | Its own | Its own |
| Context sharing with sub-agents | Its own model | Its own model |
| Available features | Spec-driven development and Powers only in the IDE | Plan mode and code intelligence only in the CLI |
The CLI's lineage is worth knowing too. Kiro CLI shipped on November 17, 2025, the day Kiro became generally available, as version 1.20.0. Kiro's documentation describes it as "the next update of the Q CLI" (Upgrading from Amazon Q Developer CLI ). That lineage makes it easier to see why the first version number was 1.20.0 rather than 1.0.
Permissions differed by surface as well. The old IDE had only two modes, Autopilot and Supervised, and the Kiro documentation puts it this way: "There was no way to allow some operations while blocking others — it was all-or-nothing." (IDE 0.x reference ) Another problem was that both surfaces set permissions per tool. To enforce something like "don't read
.env files," you had to block every tool that could read files (read, glob, grep, code intelligence) one by one. Miss one, and the agent could still read the file through a different tool.The costs piled up. In the post's words: "Every new capability had to be built and maintained three times … Bugs had to be fixed three times."
The bigger problem was that this structure couldn't deliver what the Kiro team had pictured from the start: you close your laptop at the end of the day and your session keeps running in the cloud, you check on it from your phone on the way to get coffee, and you open the IDE the next morning and pick up where you left off. That picture requires sessions to move across surfaces and devices. But the three harnesses shared no session format, no tool set, and no configuration model. So moving a session started on one surface to another was, as the team wrote, "architecturally impossible."
The turning point: preparing to launch the web client publicly
The Kiro team considered another option: keep three harnesses and agree on behavior contracts for the agent. They decided against it, because every new feature would then need a spec, three implementations, and ongoing validation that the three behave identically.
The trigger was preparing to launch Kiro on the web publicly. Shipping the web client with its own dedicated agent would keep the cost of maintaining three separate implementations growing. Instead, the team decided to build a single new harness that combined what all three teams had learned. According to the post, they built it with Kiro itself.
How they merged it: a separate process, not a library
The most interesting decision in this story is that the harness was built as a standalone server process, not a library.
Packaging shared code as a library and compiling it into each client looks simpler. But the Kiro team writes that earlier attempts showed this doesn't enforce the boundary: client code ends up calling internal methods that were never meant to be exported, or layering its own agent logic on top of the library. Then the implementations diverge again. A separate process puts a real wall between client and agent. The only way across is the defined protocol, and each client can stay in whatever language and runtime it already uses.
The roles split like this:
- The harness: everything on the agent side, such as tools, context, permissions, and communication with the model
- The surface (client): how the user interacts with the agent and how the agent's work is presented
For the protocol between them, they chose ACP (Agent Client Protocol), a standard specification for how editors and AI coding agents communicate, which reached 1.0 in June 2026. The Kiro team describes ACP this way: "Think of it like LSP (Language Server Protocol), but for AI agents" (Kiro adopts ACP , February 5, 2026). Kiro CLI already supported ACP before the merge, to connect with editors such as JetBrains IDEs and Zed. With the unified harness, Kiro's own surfaces talk to the harness over the same protocol, not just third-party editors.
- Local surfaces (IDE and CLI) launch the harness as a child process and connect over standard input/output (stdio).
- The web client and the iOS app connect over WebSocket to a harness running in a cloud sandbox.
- Kiro-specific features such as live steering, the spec workflow, and multi-scope permissions were added under the
_kiro/namespace, following ACP's extension rules. Adding up the numbers the Kiro team gives, that's more than 50 methods and notification types.
You can see this separate process in action when testing on a Mac. Run kiro-cli 2.30.0 with verbose logging (
-v) and --v3, and one of the first log lines says KAS (Kiro Agent Server) is starting. Without --v3, that line doesn't appear. The current CLI install contains both the old engine and the new harness, and a flag chooses between them.What changed once it became one
The first effect of the merge is that features once limited to one surface have started reaching others. The configuration formats have converged too.
| Area | Before the merge | Unified harness |
|---|---|---|
| Spec-driven development | IDE only | Also in the CLI (/spec new) and on the web |
| Custom agents | Behaved differently on each surface | Markdown files in .kiro/agents/. Tools are selected with tags such as read, write, and shell instead of individual tool names |
| Hooks | .kiro.hook in the IDE, inside the agent configuration in the CLI | Common format is .kiro/hooks/*.json. CLI V3 also supports a list in the same format inside the agent configuration |
| Compaction of long conversations | Each harness had its own strategy, so long sessions behaved differently by surface | One implementation |
| Permissions | Different syntax on each surface, per tool | One set of capability-based rules |
The biggest change is in permissions. The new permission model is backed by Cedar , a formally verified policy language. Tools are grouped into capabilities by what they do:
fs_read, fs_write, shell, web_fetch, mcp, subagent, and others. That means the earlier "don't read .env" can be written as a single rule. Below is an example made for illustration, using the syntax from the Kiro permissions documentation .1
2
3
4
5
6
rules:
- capability: fs_read
effect: deny
match:
- "**/.env"
- "**/.env.*"
Denying
fs_read blocks every tool that reads files. You don't have to list the tools one by one, and the same rule applies to any read tool added later. When rules overlap, deny takes precedence over ask, and ask over allow, regardless of scope (user-wide, workspace, agent, and so on). Kiro also enforces some immutable rules of its own — for example, the agent cannot modify its own permission files.The second effect is that changing the harness alone can ship a new feature to several surfaces at once. A change that doesn't touch the ACP boundary needs no client code changes. In the August post, the Kiro team gave three examples: live reload of agent files you edit in
.kiro/agents/ mid-session, global hooks in ~/.kiro/hooks/ that fire in every workspace, and policy presets that bundle commonly used rules under a name. All three, they say, shipped with a harness update alone, without client code changes.That doesn't mean "every surface is exactly the same"
It would be wrong to read the unified harness as "the exact same program on every surface." The Kiro team says so plainly: "The harness is not one-size-fits-all." A surface can provide its own tools and suppress the harness's built-in ones. For example, the IDE uses its own tools built on Code OSS APIs instead of the harness's tools that read and write files directly. Feature support still differs by surface, too. On the web, for instance, the agent runs in an isolated cloud sandbox, so
permissions.yaml rules and per-action approvals don't apply (Permissions ). For hooks, the support table in the Hooks documentation marks only the IDE and the CLI, leaving web and mobile blank. The How Kiro works page says each feature page shows in a table which surfaces a capability hasn't reached yet.So here is how I understand the merge: what the agent does (how it reads configuration, how it decides permissions, how it compacts) has converged, while how people work with the agent still differs by surface.
Why the version numbers are confusing
If you follow Kiro's history, version numbers are where you get stuck most often.
kiro-cli --version says 2.30.0, yet the docs and announcements talk about "CLI 3.0" and "V3." That's because the numbers refer to two different things.- Product version: the number of the app you installed. Right now the CLI is 2.30.0 and the IDE is 1.2.x.
- Engine generation: which harness handles the conversation. CLI 2.x contains both the old engine (V2) and the unified harness (V3).
Once you separate the two, most of the confusion goes away.
- Kiro's general availability wasn't 1.0. At GA on November 17, 2025, the IDE was at 0.6.
- Kiro CLI's first version was 1.20.0, not 1.0. Kiro's documentation describes Kiro CLI as the next update of Amazon Q Developer CLI.
- CLI 2.0 was not the release that brought in the unified harness. CLI 2.0, released on April 13, 2026, made the new terminal UI (TUI) the default and added headless mode and Windows support. The new harness (V3) first appeared later, in 2.8.0 in June, alongside the existing 2.x engine.
- CLI 3.0 hasn't shipped yet. For now, "V3" is an engine you select with
--v3inside a 2.x install. - The IDE switched engines at 1.0. The CLI is set to mark its engine switch with a single number (3.0), while the IDE moved to the unified harness when it went from 0.x to 1.0.
Here it is as a timeline.
| Date | What happened |
|---|---|
| 2025-07-14 | IDE 0.1 preview released |
| 2025-11-17 | Kiro general availability (IDE 0.6), Kiro CLI 1.20.0 released |
| 2026-02-05 | CLI support for ACP announced |
| 2026-04-13 | CLI 2.0: new terminal UI by default, headless mode, Windows support |
| 2026-06 | ACP 1.0 |
| 2026-06-17 | CLI 2.8.0: --v3 added to try V3 early. The iOS app was announced the same day (early access) |
| 2026-06-25 | IDE 1.0.0: capability-based permissions, Markdown agents, v1 hook format |
| 2026-07-22 | CLI 2.14: /upgrade-agent, which converts V2 agent configurations so they also work with V3 |
| 2026-08-03 | The Kiro team announces that four surfaces (IDE, CLI V3, web, iOS) run on the unified harness |
| 2026-09-01 | Kiro on the web generally available |
| 2026-10-09 | Announcement that CLI V3 will become the default |
| 2026-10-12 | CLI 2.30: startup prompt suggesting a switch to V3, rolled out gradually |
| End of October 2026 (planned) | CLI 3.0: V3 becomes the default |
Dates are from the Kiro changelog and the publication dates of the blog posts.
Where things stand now
By surface:
- IDE: on the unified harness since 1.0. Currently at 1.2.x.
- Web: generally available since September 1. Runs the harness in a cloud sandbox.
- Phone (iOS): still in early access. You request access and, once invited, install it through Apple TestFlight. The phone app doesn't launch a harness of its own; it connects to the same cloud sessions as the web client. Kiro says you can steer cloud sessions started from the web, the IDE, or the CLI from your phone, kick off new work, review diffs, and approve changes (Mobile ). It requires a Pro or higher paid plan and iOS 26 or later, and the mobile documentation is still marked "coming soon." Android isn't supported yet. On the Kiro mobile page , the answer to "Is Android coming?" is simply: "We're starting with iOS for now, and we'll provide updates if Android is supported in the future."
- CLI: still defaults to the old engine. On a Mac, I launched kiro-cli 2.30.0 without flags in an empty folder with no configuration. The log was the same as with
--v2, and the first screen showed "An early release of Kiro CLI V3 is now available! Try it out: kiro-cli --v3". Only with--v3did "Welcome to Kiro CLI V3!" appear.
The picture from earlier isn't complete yet, either. In the August post, the Kiro team listed what they still need to build: session packaging for moving sessions across environments, and the ability to control both local and cloud sessions from any surface. According to the team, the unified harness means each of these only has to be built once.
Interestingly, Kiro's documentation is already written as if the merge were finished. The How Kiro works page says: "Every Kiro surface (the IDE, CLI, Web, and Mobile) is a front end to that same harness." For the CLI, that sentence still carries the condition "if you choose V3."
That condition is about to go away, too. The October 9 announcement, "Kiro CLI V3 is rolling out as the default experience" , lays out the schedule:
Starting October 12, we are gradually rolling out a startup prompt inviting you to switch ahead of the CLI 3.0 release by the end of October.
Choosing "Don't ask again" in the startup prompt won't keep you on V2. The announcement says: "your setup will still be upgraded to V3 when CLI 3.0 is released at end of October." After 3.0 you can still run the old engine with
kiro-cli --v2, but the flag applies to that launch only. The announcement doesn't say how long the old engine will remain available.Some things are being retired along with CLI 3.0: the old terminal interface (Classic), inline shell autocomplete, and the CLI desktop app. Classic doesn't support V3, which is why, starting with 2.26 on September 30, launching Classic shows a deprecation notice.
The same trend is visible outside the CLI. Kiro Crew, a personal AI agent that keeps running on your own machine or on remote hardware, has gained a preview feature for choosing which harness runs a session. One option is KAS, described as "Runs the Kiro agent harness through Kiro CLI's ACP relay" (Agent backends ). The default option, however, is still "Kiro CLI."
What to check when moving to V3
Kiro says most users won't need to change their configuration when they switch. But if you've built your own custom agents, permissions, or hooks, you should check the conversion results. Because the engines were different programs, they interpret configuration differently.
Permissions use a different way of writing rules. V2 uses trusted-tool lists and per-tool settings; V3 uses rules about which action is applied to which resource. Per-tool settings and capability rules don't map one to one, so the automatic migration converts only the settings it supports. Some patterns need to be reviewed or rewritten by hand. Kiro advises running
/upgrade-agent diagnostics after migration and addressing any warnings before relying on the new rules.On a Mac with old-format agent configurations in place, launching with
--v3 for the first time ran the automatic migration, and some of those configurations got conversion warnings. Configurations that used patterns such as web_* in allowedTools didn't map to the new rules, and configurations that used the use_aws tool, which V3 doesn't have, were flagged as well. In V3, AWS CLI commands run through the shell tool and follow shell permission rules. The 2.30 changelog says the upgrade now "keeps more of your V2 agent access" when converting to V3. Don't rely on the warnings alone; compare the permission rules in the backup and the converted file as well.For hooks, check both the format and where they live. The old CLI put hooks as objects inside the agent configuration, with camelCase trigger names such as
agentSpawn. V3 uses a list format with PascalCase triggers such as SessionStart. /upgrade-agent converts old hooks into a list in the new format inside that agent's configuration. Kiro's documentation advises moving hooks that should run regardless of the agent, or be shared with the IDE, into standalone .kiro/hooks/*.json files. Hooks that can't be converted are left out of the V3 configuration and reported as warnings. In IDE 1.0, too, legacy 0.x hooks can be migrated from the Agent Hooks panel. After moving, make sure the hooks you wrote actually run.There are migration tools. Inside a session, use
/upgrade-agent. In CLI 2.29 and later, teams that keep their agents in one repository can convert a whole directory with kiro-cli agent upgrade <dir>. Run it with --dry-run first to preview the changes and warnings. The originals are backed up as <name>.json.bak.Sessions carry over in one direction only. You can resume V2 sessions in V3, but sessions created in V3 can't be opened in V2.
It also helps to know how to tell which engine you're on. If you launch interactively and see "Welcome to Kiro CLI V3!", you're on V3. To make V3 your default ahead of time, use
kiro-cli settings chat.agentEngine v3, as the announcement shows. If you want V3 for just one project, you can also put "chat.agentEngine": "v3" in that project's .kiro/settings/cli.json. In my tests with 2.30.0 on a Mac, it launched on V3 without a flag inside the folder with that setting, and on V2 in a folder without it. The CLI settings documentation explains how to store per-project values with kiro-cli settings --workspace, but it doesn't state that chat.agentEngine can be set per project.What this post can't tell you
The architecture and the reasons behind it follow the Kiro team's public posts. Which language each of the three harnesses was written in, and why a separate process was chosen over a library, come from what the Kiro team has published on its blog. This post is based solely on public posts and documentation, plus the results of running Kiro CLI, which anyone can install.
What I verified directly comes from tests on a Mac. That includes kiro-cli 2.30.0 starting on V2 without flags, KAS starting with
--v3, the project setting switching the engine, and the warnings left by the automatic migration. The startup prompt is being rolled out gradually, so you may see something different on the same version.The end-of-October release is planned, not confirmed. When CLI 3.0 will actually ship, and how long the old engine will remain available, can't be confirmed at the time of writing.
Summary
- The old Kiro was three programs that shared a name. The IDE built its harness in TypeScript, the CLI in Rust, and the web client in Python. Permissions, hooks, and session formats diverged, and every feature had to be built three times and every bug fixed three times.
- Kiro merged the harness into one separate process and connected it to the surfaces with ACP. Splitting along a process boundary instead of a library keeps the boundary intact, and a harness change alone can ship features to several surfaces together. Permissions converged on one set of Cedar-backed capability rules, and agents and hooks on one format each.
- The merge is still in progress. The IDE and the web client have moved over, and V3 is scheduled to become the CLI default in 3.0 at the end of October. If you've been using custom agents, permissions, or hooks, it's worth launching with
--v3once now and checking the conversion warnings.
References
- One agent, every surface: how we built the Kiro agent harness — Kiro blog, August 3, 2026
- Kiro CLI V3 is rolling out as the default experience — Kiro blog, October 9, 2026
- How Kiro works — Kiro documentation
- Kiro CLI V3 — Kiro documentation
- Permissions — Kiro documentation
- CLI settings — Kiro documentation
- Agent backends — Kiro Crew documentation
- Mobile — Kiro documentation
- Kiro for iOS — Kiro mobile page
- Introducing Kiro for iOS — Kiro blog, June 17, 2026
- IDE 0.x reference — Kiro documentation
- Kiro is generally available — Kiro blog, November 17, 2025
- Specialized IDEs deserve AI too: Kiro adopts ACP — Kiro blog, February 5, 2026
- Kiro changelog — CLI 1.20, 2.0, 2.8, 2.14, 2.26, 2.29, 2.30; IDE 0.1, 0.6, 1.0; Kiro on the web GA
- Agent Client Protocol
- Cedar
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article