opencode-kiro

The ACP-compliant Kiro auth plugin for opencode.

opencode learns the kiro provider and its available models (US region) from the models.dev catalog. This plugin supplies the following pieces:

• Auth via the official kiro-cli login flow (opencode auth login, then "Kiro CLI Login")
• Provider options loader: the cwd, agent, trustAllTools, mcpTimeout values opencode forwards into the SDK factory
• TUI credits display: an opt-in sidebar context box showing tokens, context usage, and Kiro credits

The kiro provider resolves to kiro-acp-ai-provider, an AI-SDK provider that talks to your locally installed kiro-cli over Kiro's Agent Client Protocol (ACP); opencode picks it up from the catalog's npm field. This is the supported integration path: requests go through kiro-cli exactly like Kiro's own IDE clients, with no credential scraping and no reuse of Kiro credentials against other providers.

Prerequisites

| Requirement | Notes | |---|---| | kiro-cli | Must be installed and on PATH; a Kiro subscription / AWS Builder ID account | | Node.js >= 20 | Enforced via engines.node. | | opencode >= 1.16.0 | Enforced via engines.opencode on released builds. The shipped catalog must include the kiro provider (see Troubleshooting). |

Install

opencode plugin opencode-kiro

(alias: opencode plug opencode-kiro; add --global/-g to install into your global config instead of the project)

The installer reads this package's exports and detects both plugin entrypoints (./server and ./tui), then patches both config files automatically:

• .opencode/opencode.json: the server plugin (auth)
• .opencode/tui.json: the TUI plugin (credits sidebar box)

(with --global: ~/.config/opencode/opencode.json and ~/.config/opencode/tui.json)

You do not add a provider.kiro block; opencode loads the kiro provider and its models straight from the models.dev catalog. Then disable the builtin context box, see Credits in the sidebar.

Manual alternative

Add the package name to the plugin array of both files yourself (in the project's .opencode/ directory, at the project root, or in the global ~/.config/opencode/, all are valid config locations):

opencode.json:

{
  "plugin": ["opencode-kiro"]
}

tui.json:

{
  "plugin": ["opencode-kiro"],
  "plugin_enabled": { "internal:sidebar-context": false }
}

(plugin_enabled is the credits sidebar step, recommended now, explained below.)

Local development (path source)

Run a local checkout without npm: build first, then reference the repo directory by absolute path in both plugin arrays:

git clone https://github.com/NachoFLizaur/opencode-kiro && cd opencode-kiro
npm install && npm run build

{ "plugin": ["/absolute/path/to/opencode-kiro"] }

opencode resolves the right entrypoint per file from the package exports. Note that path-sourced TUI plugins must export an id (opencode rejects them otherwise); this package ships { id: "opencode-kiro", tui }, so the id (and your plugin_enabled keys) are identical across path and npm installs.

Because the provider now comes from the catalog rather than the plugin, a local checkout also needs a catalog that includes kiro. opencode reads its catalog from OPENCODE_MODELS_PATH when set; point it at an api.json that contains the kiro provider (for example one generated from a models.dev checkout):

OPENCODE_MODELS_PATH=/path/to/api.json opencode models | grep '^kiro/'

Until the catalog opencode loads contains kiro, the provider will not appear regardless of this plugin being installed (the plugin only adds auth, not the provider definition).

Auth

opencode auth login

Select the Kiro (plugin) provider, then the Kiro CLI Login method:

• Already logged in to kiro-cli: immediate success; the existing kiro-cli session is reused.
• Not logged in: the plugin launches kiro-cli login, which opens a browser window. Complete the login there; the plugin polls for up to 120 seconds and stores the credential when kiro-cli reports success.

If the flow times out, authenticate directly with kiro-cli (kiro-cli login) and run opencode auth login again; the fast path then completes immediately.

Note: opencode will also surface kiro if the KIRO_API_KEY environment variable is set, because the catalog entry declares env: ["KIRO_API_KEY"]. The intended auth path for this plugin is still Kiro CLI Login above (it reuses your local kiro-cli session); the env var is a secondary route opencode offers for any catalog provider.

Models

This plugin supports all models in the US region, defined in the models.dev kiro catalog entry. opencode loads them from there. List them with:

opencode models           # lists kiro/auto, kiro/claude-opus-4.8, ...
opencode run -m kiro/auto "hello"

Image input is capability-driven: paste an image path into the TUI prompt and image-capable models receive it as an attachment.

Credits in the sidebar

Kiro is subscription-metered: requests consume credits, and the dollar cost opencode normally displays for Kiro turns is always $0.00. The plugin therefore registers a full replacement for the built-in sidebar context box, showing tokens, context percentage, and a spend line.

The spend line adapts to what the session actually used:

• Dollars only (no Kiro turns): the builtin's exact $X.XX spent line, so non-Kiro sessions look identical to the built-in box.
• Credits only (Kiro turns, no dollar cost): a single N credits line.
• Both (the session used a dollar-based model AND Kiro in one session): two stacked lines, $X.XX spent then N credits, so neither figure is hidden.

Disable the builtin box in tui.json so only the replacement renders:

{
  "plugin_enabled": { "internal:sidebar-context": false }
}

Without this you will see two context boxes (cosmetic duplication: the builtin one plus the plugin's). The credits value and its unit come from the metadata the SDK attaches to each message part (kiro-cli reports the unit); nothing is hardcoded client-side.

Trade-off: the replacement box applies to every session and disabling the builtin is global. The replacement reproduces the builtin $X.XX spent line for non-Kiro sessions (and stacks it above credits when a session used both), so mixed-provider users keep dollar cost in the sidebar; if you prefer the original built-in box, leave it enabled at the cost of the duplicate box.

Known limitation

Credits render in the TUI only. Two TUI surfaces show them: the sidebar context box (above) and the input/prompt meta row chip (session_prompt_right), which sits above the host's $ cost chip. Every other cost surface (ACP clients, the web app, desktop, web share pages, and CLI cost output) shows $0.00 for Kiro sessions. The models.dev catalog declares Kiro's per-token cost as 0 (it is a subscription-metered provider with no per-token pricing), so opencode core computes $0.00 everywhere it renders dollar cost. That is expected, not a defect. A cross-surface credits display would require opencode core changes and is intentionally out of scope for this plugin.

How it works

• Provider & models (models.dev): opencode loads the kiro provider and its full model list from the models.dev catalog. This plugin does not define any provider or model config of its own; there is no config hook.
• SDK resolution (resolveSDK): opencode reads the catalog's npm field (kiro-acp-ai-provider), installs that package into its package cache on first model use, and imports it. This plugin's auth loader supplies the provider options (cwd, agent, trustAllTools, mcpTimeout, contextWindows) that opencode forwards into createKiroAcp(...). The loader relays each model's limit.context (from models.dev, via opencode's resolved catalog) into the SDK's contextWindows map keyed by api.id, so the SDK keeps no hardcoded per-model data and falls back to 1,000,000 for any model absent from the relay.
• Auth (this plugin): registers the "Kiro CLI Login" OAuth method (kiro-cli login flow) plus the options loader above. The same plugin also imports verifyAuth from kiro-acp-ai-provider to check kiro-cli installation/login state.
• Session affinity & reset (in-SDK): the SDK keys kiro-cli sessions off opencode's x-session-affinity header, isolates tool-less utility calls (title generation) on an ephemeral session, detects prompt-history divergence (fork/undo), and starts a fresh kiro session when needed. No host-side session plumbing.
• Credits metadata: the SDK attaches { kiro: { credits, creditsUnit } } to the metadata of the final message part of each turn; opencode persists it, and the TUI plugin sums it per assistant message (deduped across text/reasoning parts) for the sidebar.

Troubleshooting

| Symptom | Cause / fix | |---|---| | kiro-cli is not installed during auth | Install kiro-cli from https://kiro.dev/docs/cli/ and ensure it is on PATH for the opencode process. | | Auth times out after ~120s | Complete the browser login faster, or run kiro-cli login yourself, then re-run opencode auth login (fast path). | | Two "Context" boxes in the sidebar | Add "plugin_enabled": { "internal:sidebar-context": false } to tui.json (see Credits in the sidebar). | | No credits line / credits stay 0 | Credits appear after the first completed kiro turn; cancelled turns and turns without usage metadata contribute nothing. Check the TUI plugin is active in the Plugins dialog (and listed in tui.json). | | Credits sidebar box never appears (even with tui.json configured correctly) | The TUI credits box renders only when opencode-kiro is resolvable in opencode's package cache. If the package is missing from the cache the box silently does not appear. Fix: ensure opencode-kiro is installed so it resolves in the cache. Do not manually clear the package cache: clearing can trigger a flaky on-demand refetch that fails with an "unknown git error". | | kiro provider not showing in opencode models | The provider comes from the models.dev catalog, not this plugin. Ensure your opencode version ships a catalog that includes kiro (run opencode models --refresh to update the cache). For local development, point opencode at a kiro-inclusive catalog via OPENCODE_MODELS_PATH=/path/to/api.json (see Local development). | | sdk.languageModel is not a function | A stale kiro-acp-ai-provider from before the 2.0.x line resolved from opencode's package cache. Remove the cached copy ($XDG_CACHE_HOME/opencode/packages/kiro-acp-ai-provider, default ~/.cache/opencode/packages/...) and retry; the factory auto-discovery clash was fixed in the 2.0.x line, and this plugin currently pins 2.0.2. | | Path install rejected (must export id) | Run npm run build in your checkout first and reference the repo root (both entry modules export ids). | | Provider visible but runs fail | The provider is selectable (from the catalog) before any credential exists. Run opencode auth login first. |

Development

npm install
npm run typecheck   # tsc --noEmit
npm run build       # tsup builds dist/server.js + dist/tui.js (+ d.ts)
npm test            # vitest

License

MIT © Nacho F. Lizaur