opencode-kiro-auth
简体中文 · English
OpenCode plugin that lets OpenCode use AWS Kiro (CodeWhisperer) as a model
provider — Claude Sonnet, Opus, and Haiku, plus the other models Kiro proxies
(OpenAI GPT 5.6, DeepSeek, GLM, MiniMax, Qwen3) — with substantial trial
quotas.
Table of Contents
Features
- Multiple auth methods: AWS Builder ID (IDC), IAM Identity Center (custom
Start URL), and Kiro Desktop (CLI-based) authentication.
- Auto-sync Kiro CLI: automatically imports and synchronizes active
sessions from your local
kiro-cli SQLite database.
- Gradual context truncation: intelligently prevents error 400 by reducing
context size dynamically during retries.
- Intelligent account rotation: prioritizes multi-account usage based on
lowest available quota.
- High-performance storage: efficient account and usage management using
native Bun SQLite.
- Native thinking mode: full support for Claude reasoning capabilities via
virtual model mappings.
- Kiro effort mapping: maps OpenCode thinking budgets to Kiro's native
effort levels automatically.
- Automated recovery: exponential backoff for rate limits and automated
token refresh.
Installation
Add the plugin to your opencode.json or opencode.jsonc:
{
"plugin": ["@sunerpy/opencode-kiro-auth"]
}
That alone registers the kiro-auth provider with a default model set. To
customize which models are exposed (including thinking variants), see
Models and the full catalog in
docs/MODELS.md.
Setup / Auth
- Authentication via Kiro CLI (recommended):
- Log in directly in your terminal with
kiro-cli login.
- The plugin automatically bootstraps a minimal
kiro-auth placeholder in
OpenCode's auth.json when it detects the Kiro CLI database, then
imports and synchronizes your active session on startup.
- For AWS IAM Identity Center (SSO/IDC), the plugin imports both the token
and device registration (OIDC client credentials) from the
kiro-cli
database.
- Direct authentication:
- Run
opencode auth login.
- Select
Other, type kiro-auth, and press enter.
- You'll be prompted for your IAM Identity Center Start URL and
region (
sso_region). Leave it blank for AWS Builder ID, or
enter your company's Start URL (e.g.
https://your-company.awsapps.com/start) for IAM Identity Center
(SSO).
- Note: the TUI
/connect flow does not currently run plugin OAuth
prompts (Start URL / region), so Identity Center logins may fall back to
Builder ID unless you use opencode auth login (or preconfigure
defaults in ~/.config/opencode/kiro-auth-plugin/kiro.json).
- For IAM Identity Center, you may also need a profile ARN
(
profileArn) — auto-detected from kiro-cli profile if available, or
set idc_profile_arn manually.
- A browser window opens directly to AWS's verification URL (no local auth
server). If it doesn't, copy/paste the URL and enter the code OpenCode
prints.
- Configuration is automatically managed at
~/.config/opencode/kiro.db.
Configuration
Plugin-wide behavior (auth sync, account selection, retry limits, effort
mapping) lives in ~/.config/opencode/kiro-auth-plugin/kiro.json. See
docs/CONFIGURATION.md for the full example and every
option.
New default keys are backfilled into an existing kiro.json automatically when
the plugin loads (additive only — your existing values are never changed). For
multi-account or long-idle setups, enable
token keep-alive
(token_keepalive_enabled: true) to keep idle accounts' tokens fresh while
OpenCode is running.
The SDK transport uses fresh HTTP sockets by default
("sdk_http_keep_alive": false) to reduce Bun stale-connection
ECONNRESET failures without serializing requests or delaying live tokens.
Each request pays one additional TCP/TLS handshake, while active streams and
multiple OpenCode processes remain concurrent. For workloads that prefer task
continuity over live output even after a mid-stream failure,
"stream_buffer_until_complete": true remains available. See
stream recovery configuration for the
different latency and quota tradeoffs.
OpenCode compaction summaries are buffered atomically by default
("compaction_buffer_until_complete": true): a failed summary attempt is
discarded before OpenCode can persist a partial summary, while ordinary chat
requests still stream live. Recovery attempts on the same account also reuse
one transformed Kiro request and conversationId. Reusing that wire identity
after an account switch remains experimental and disabled by default via
stream_recovery_reuse_conversation_id_across_accounts.
Paid-overage protection is on by default; see
Overage protection before disabling
stop_on_overage.
Running multiple OpenCode processes at once? distribute_across_processes
(default true) and per_request_spread (default false) control how load
spreads across accounts — see
Account distribution across processes.
Detailed API request logging is off by default. Logs now rotate into compact
NDJSON segments, gzip in the background, and are bounded to 7 days / 512 MiB by
default. See
log retention and compression.
Multiple accounts & rotation
You can register more than one Kiro account and let the plugin spread
requests across them for combined quota and automatic failover.
Adding accounts, two ways:
- Run
opencode auth login, select kiro-auth, and complete a Builder ID
or IAM Identity Center login. Run this once per account — each distinct
AWS identity is stored separately in kiro.db. Re-running login for the
same identity updates it in place; logging in with a different identity
adds a new account.
- Auto-sync from Kiro CLI: with
auto_sync_kiro_cli: true (opt-in, default
false), the plugin imports credentials from your local kiro-cli
database. Note kiro-cli stores only one token per auth method, so it
cannot represent multiple accounts — manual opencode auth login per
account (option 1) is the supported multi-account path.
Rotation strategy — set account_selection_strategy in
~/.config/opencode/kiro-auth-plugin/kiro.json:
| Strategy |
Behavior |
Default |
lowest-usage |
Each request picks the healthy account with the lowest used quota |
✅ |
round-robin |
Cycles through accounts in order |
|
sticky |
Always uses the first account; switches only when it becomes unhealthy |
|
Automatic failover requires no configuration: a rate-limited or 403
account is marked unhealthy and the next healthy account takes over. If every
account is rate-limited, the plugin waits out the minimum reset time and
retries. A circuit breaker trips after 10 consecutive selection failures to
avoid a hot loop.
Removing an account: run opencode auth login, select kiro-auth,
choose "Remove a Kiro account (N stored)", then pick the account from the
dropdown (or cancel).
Note: removal is persistent. Once you remove an account it stays
removed across restarts and Kiro CLI auto-sync — it won't come back on its
own. To re-add it, just log in with that account again via
opencode auth login. See
Removing accounts & the removal tombstone
for how this works.
Full config key reference: docs/CONFIGURATION.md.
Usage display
The plugin reads real quota from Kiro's usage API (usedCount/limitCount
per account, e.g. 929/10000) and surfaces it in three places:
- Auth menu label — running
opencode auth login and selecting
kiro-auth shows [current: <email> <used>/<limit> (<pct>%)] on the
first login method; with multiple accounts they're joined with ·,
capped at 3 with a +N more suffix.
- Startup toast — once per plugin init, a toast shows
Kiro usage (<email>): <used>/<limit> (<pct>%) a few seconds after
OpenCode starts, turning yellow (warning) at ≥90% usage.
- Runtime warning — a warning toast fires whenever a selected account
is at ≥90% usage.
There is no persistent usage widget in the TUI status bar — usage only
shows up via the label and toasts above. To check usage at any time, either
restart OpenCode (triggers the startup toast) or query kiro.db directly:
python3 -c "import sqlite3;r=sqlite3.connect('$HOME/.config/opencode/kiro.db').execute('SELECT email,used_count,limit_count FROM accounts').fetchall();[print(f'{e}: {u}/{l} (left {l-u})') for e,u,l in r]"
Models
The default install exposes Claude Sonnet/Opus/Haiku plus the open-weight
models Kiro proxies. To pin an exact model list or configure thinking-budget
variants, paste the full catalog from docs/MODELS.md into
your provider.kiro-auth.models block.
Thinking budgets map to Kiro's native effort field automatically:
| OpenCode budget |
Kiro effort |
<= 10000 |
low |
<= 20000 |
medium |
<= 28000 |
high |
> 28000 |
max |
Details and the full JSON example: docs/MODELS.md.
Note: OpenCode's per-agent thinking level (--variant / an agent's
variant in oh-my-openagent.json) isn't honored per agent by this
plugin — OpenCode consumes it upstream. Use the global effort key in
kiro.json instead. See
Reasoning effort for details.
Note: Reasoning-capable Kiro models (Claude Opus 4.x and other
reasoning-capable models) stream their chain-of-thought as a separate
event, which the plugin surfaces as OpenCode's own reasoning block — shown
as "Thought: <duration>" above the final reply. No config needed. See
Reasoning display for details.
Note: Per-request thinking level via model variants — pick
kiro-auth/claude-opus-5-xhigh (or similar) straight from the model
list to pin an explicit Kiro effort level for that model, no kiro.json
edit needed. Base models like claude-opus-5 remain available and keep
using the global effort setting. See docs/VARIANTS.md
for the full variant list and why they exist.
Troubleshooting
Common issues — 403/AccessDeniedException with IAM Identity Center, "No
accounts", /connect vs opencode auth login, and Kiro CLI OAuth users whose
sync doesn't start — are covered in
docs/TROUBLESHOOTING.md.
Kiro upstream event stream failed unexpectedly means an HTTP 200 event stream
failed during iteration and the bounded recovery policy was exhausted or could
not safely continue. It is distinct from the benign
Kiro stream ended without completion metadata warning. Compaction summaries
are already atomic by default; for ordinary requests, enable
stream_buffer_until_complete when task continuity is more important than
seeing tokens arrive live.
Assistant prose is never interpreted as a recovery control signal. A non-empty
clean EOF completes normally regardless of whether the response describes a next
step. With stream_recovery_mode set to reasoning_restart or exact_replay, the
plugin may spend one additional same-account SDK send only for a fully empty clean
EOF with no tool output or tool intent. Iterator failures and unclosed tool intent
continue through the configured recovery tier; every additional SDK send consumes
quota.
Migration
If you're upgrading from a version that used the provider id kiro instead of
kiro-auth:
- A stale
kiro key in OpenCode's auth.json will be claimed by OpenCode's
built-in kiro provider (models.dev provider #91), not this plugin.
Remove or ignore that key — this plugin now bootstraps and uses kiro-auth.
- Any config or session string of the form
kiro/<model> must become
kiro-auth/<model> (e.g. kiro/claude-sonnet-4-5 →
kiro-auth/claude-sonnet-4-5).
Local plugin development
Point OpenCode directly at your local repo path in opencode.json or
opencode.jsonc:
{
"plugin": ["/path/to/opencode-kiro-auth"]
}
Then build and restart OpenCode to pick up changes: bun run build.
Development
This project uses Bun — it is the only supported package manager for
development. There is no package-lock.json; bun.lock is the single
lockfile, and both CI and the release workflow install with bun install
(npm is used only to publish the built package). Don't run npm install or
npm ci here.
The Makefile is the single source of truth for local checks and
mirrors CI:
make install # bun install
make ci # typecheck + fmt-check + test (what CI runs)
make build # tsc + fix-esm-imports -> dist/
Agent contributors: see AGENTS.md for the codebase architecture
map, invariants that must not break, and the CodeGraph-assisted workflow.
Releasing
Releases are automated with
release-please:
- Use Conventional Commits for commit
messages and pull request titles (
feat:, fix:, chore:, …) — these drive
the next version bump automatically.
- release-please opens and maintains a release pull request on
main.
Merging that PR cuts the git tag + GitHub Release and triggers the
workflow that runs typecheck/test/build and then publishes to npm.
- Contributors never hand-edit the version in
package.json or the files under
changelog/ — release-please maintains both.
Storage
Linux/macOS:
- SQLite database:
~/.config/opencode/kiro.db
- Plugin config:
~/.config/opencode/kiro-auth-plugin/kiro.json
- Logs:
~/.config/opencode/kiro-auth-plugin/logs/
- Refresh and keep-alive locks:
~/.config/opencode/kiro-auth-plugin/
Windows:
- SQLite database:
%APPDATA%\opencode\kiro.db
- Plugin config:
%APPDATA%\opencode\kiro-auth-plugin\kiro.json
- Logs:
%APPDATA%\opencode\kiro-auth-plugin\logs\
- Refresh and keep-alive locks:
%APPDATA%\opencode\kiro-auth-plugin\
Existing config, logs, and stale flat lock files are migrated automatically on
first startup; no action is needed. The SQLite database deliberately remains at
the flat opencode/kiro.db path because moving a live database during an upgrade
is unsafe. Logs are automatically rotated, gzip-compressed, and pruned according
to the retention settings in kiro.json.
Acknowledgements
Special thanks to AIClient-2-API
for providing the foundational Kiro authentication logic and request patterns.
Upstream sync
This package is a fork of
tickernelz/opencode-kiro-auth.
Upstream fixes and improvements are tracked via the upstream git remote
(https://github.com/tickernelz/opencode-kiro-auth.git) and cherry-picked into
this fork as needed.
Note: AIClient-2-API (credited
above) is licensed under GPLv3, a strong copyleft license. Because this
project's Kiro authentication logic and request patterns are derived from it,
this project is now licensed under GPLv3 as well, to comply with
AIClient-2-API's copyleft requirements.
Disclaimer
This plugin is provided strictly for learning and educational purposes.
It is an independent implementation and is not affiliated with, endorsed by,
or supported by Amazon Web Services (AWS) or Anthropic.
Use of this plugin is at your own risk.
Feel free to open a PR to optimize this plugin further.
License
GPL-3.0-or-later, see LICENSE