developersIO
[アップデート] Kiro CLI 2.3 で KIRO_HOME 環境変数やキーバインドのカスタマイズが追加されたので確認してみた

[アップデート] Kiro CLI 2.3 で KIRO_HOME 環境変数やキーバインドのカスタマイズが追加されたので確認してみた

Kiro CLIKiroAWS
2026.05.13

いわさです。

これまで Kiro CLI のグローバル設定やエージェント定義は ~/.kiro ディレクトリに固定されていました。
複数のプロファイルを使い分けたい場合や、コンテナ環境で状態を分離したい場合に不便な状態でした。
また、V2 TUI のキーバインドがデフォルト固定で、他のツールとキーが競合する場合に回避手段がありませんでした。

先日 Kiro CLI 2.3.0 がリリースされ、KIRO_HOME 環境変数によるディレクトリの変更や、V2 TUI のキーバインドカスタマイズなどが追加されました。

https://kiro.dev/changelog/cli/2-3/

今回のリリースには以下の 4 つの機能が含まれています。

  • OAuth Client ID for MCP Servers — Dynamic Client Registration (DCR) に対応していない HTTP ベースの MCP サーバー（Slack、GitHub、Figma など）に対して、事前登録した oauth.clientId を設定できるようになった
  • KIRO_HOME 環境変数 — ~/.kiro ディレクトリを任意の場所に変更できる
  • 新ターミナルで一部キーバインドをカスタマイズできるように — cancel、close-menu、quit のキーバインドを変更できる
  • Agent Output Side Channels — シェルコマンドの出力を $AGENT_DISPLAY_OUT と $AGENT_CONTEXT_OUT の 2 つのチャネルに分離できる

今回こちらを確認してみたので紹介します。

KIRO_HOME 環境変数を使ってみる

KIRO_HOME は、Kiro CLI がグローバルエージェント、ステアリング、スキル、設定などを読み書きするディレクトリを変更する環境変数です。
公式ドキュメントには以下のように記載されています。

KIRO_HOME: Overrides the ~/.kiro directory used for global agents, prompts, skills, steering, settings, and sessions. Useful for keeping multiple independent Kiro profiles on the same machine.

https://kiro.dev/docs/cli/reference/settings/#environment-variables

まず、通常の ~/.kiro を使った場合のグローバルエージェント一覧を確認してみます。
kiro-cli agent list はワークスペースとグローバルのエージェント一覧を表示するコマンドです。

$ kiro-cli agent list
Workspace: ~/work/hoge0513kiro/.kiro/agents
Global:    ~/.kiro/agents

* kiro_default     (Built-in)    Default agent
  default          Global        This is an agent migrated from profile context
  hoge0923agent    Global        
  kiro_help        (Built-in)    Help agent that answers questions about Kiro
                                  CLI features using documentation
  kiro_planner     (Built-in)    Specialized planning agent that helps break
                                  down ideas into implementation plans

Global: ~/.kiro/agents と表示されており、default や hoge0923agent といった自分で作成したカスタムエージェントが見えています。

次に、KIRO_HOME を別のディレクトリに向けてみます。
テスト用のエージェントを配置しておきます。

$ mkdir -p /tmp/kiro-home-test2/agents
$ echo '{"name":"test-agent","description":"KIRO_HOME test agent","prompt":"You are a test agent."}' \
    > /tmp/kiro-home-test2/agents/test-agent.json

この状態で KIRO_HOME を指定してエージェント一覧を確認します。

$ KIRO_HOME=/tmp/kiro-home-test2 kiro-cli agent list
Workspace: ~/work/hoge0513kiro/.kiro/agents
Global:    /tmp/kiro-home-test2/agents

* kiro_default    (Built-in)    Default agent
  kiro_help       (Built-in)    Help agent that answers questions about Kiro CLI
                                 features using documentation
  kiro_planner    (Built-in)    Specialized planning agent that helps break down
                                 ideas into implementation plans
  test-agent      Global        KIRO_HOME test agent

Global: のパスが /tmp/kiro-home-test2/agents に変わりました。
通常の ~/.kiro/agents にあった default や hoge0923agent は見えなくなり、代わりに /tmp/kiro-home-test2/agents/ に配置した test-agent が表示されています。

設定値も同様に分離されます。
kiro-cli settings list は現在の設定値を一覧表示するコマンドです。
通常の ~/.kiro を使った場合はいくつかの設定が入っています。

$ kiro-cli settings list
autocomplete.disable = false
autocomplete.immediatelyExecuteAfterSpace = false
autocomplete.theme = "dark"
chat.enableKnowledge = false (global)
chat.enableThinking = false (global)
mcp.loadedBefore = true (global)
telemetry.enabled = false (global)
chat.ui = "tui" (global)

KIRO_HOME を変更すると、設定も完全に独立します。

$ KIRO_HOME=/tmp/kiro-home-test2 kiro-cli settings list --all | head -12
telemetry.enabled
  Description: Enable/disable telemetry collection (boolean)
  Current: not set

telemetryClientId
  Description: Legacy client identifier for telemetry (string)
  Current: not set

codeWhisperer.shareCodeWhispererContentWithAWS
  Description: Share content with CodeWhisperer service (boolean)
  Current: not set

すべて not set になっていることがわかります。

グローバルエージェント、ステアリング、設定がすべて切り替わるので、例えば仕事用と個人用でエージェント構成やステアリングルールを完全に分けたい場合に使えます。
コンテナ環境で ~/.kiro をマウントせずに別の場所を指定するといった使い方もできますね。

V2 TUI のキーバインドをカスタマイズしてみる

Kiro CLI には TUI（Terminal UI）と Classic の 2 つのインターフェースがあり、2.0 以降は TUI がデフォルトになっています。
今回、この TUI で以下の 3 つのアクションのキーバインドを変更できるようになりました。

設定キー デフォルト 説明
chat.keybindings.cancelStream esc ストリーミング中のレスポンスをキャンセル
chat.keybindings.closeMenu esc スラッシュコマンドメニューやパネルを閉じる
chat.keybindings.quit ctrl+c CLI を終了（2回連続で押す）

公式ドキュメントによると、ctrl+、shift+、alt+/meta+ の修飾キーと単一キーの組み合わせで指定できるとのこと。
無効な値を設定した場合はデフォルトにフォールバックされます。

Override the terminal UI shortcuts for cancelling a response, closing overlay menus, and quitting the session. Values use ctrl+, shift+, and alt+/meta+ modifiers with a single key (for example ctrl+shift+q, esc). Invalid values fall back to the built-in default.

実際に設定して TUI で動作を確認してみます。

$ kiro-cli settings chat.keybindings.cancelStream "ctrl+x"

$ kiro-cli settings chat.keybindings.cancelStream
ctrl+x (global)

$ kiro-cli settings chat.keybindings.quit "ctrl+shift+q"

$ kiro-cli settings chat.keybindings.quit
ctrl+shift+q (global)

$ kiro-cli settings chat.keybindings.closeMenu "ctrl+["

$ kiro-cli settings chat.keybindings.closeMenu
ctrl+[ (global)

すべて問題なく設定できました。

この状態で TUI を起動し、cancelStream の動作を確認してみます。
長めの質問をしてストリーミング中の画面を見ると、(Ctrl+X to cancel) と表示されています。

1350B024-9613-49E3-9DF6-493221C78672.png

デフォルトでは (Esc to cancel) と表示される箇所が、設定した Ctrl+X に変わっていることがわかります。
実際に Ctrl+X を押すと Cancelled streaming と表示されてストリーミングが中断されました。

A3A93911-EAD3-401F-B4FE-07261448850E_4_5005_c.jpeg

設定を削除するとデフォルトに戻ります。

$ kiro-cli settings --delete chat.keybindings.cancelStream
Removing "chat.keybindings.cancelStream"

$ kiro-cli settings --delete chat.keybindings.quit
Removing "chat.keybindings.quit"

$ kiro-cli settings --delete chat.keybindings.closeMenu
Removing "chat.keybindings.closeMenu"

Agent Output Side Channels を試してみる

Kiro CLI のエージェントがシェルコマンドを実行する際、これまでは stdout に出力された内容がすべてエージェントのコンテキストに取り込まれていました。
ビルドログのように大量の出力があるコマンドを実行すると、コンテキストウィンドウが圧迫されてしまいます。

今回のアップデートで、エージェントが実行するシェルコマンドの中で使える 2 つの出力先が追加されました。
仕組みとしては、エージェントがシェルコマンドを実行する際に Kiro CLI が自動的に $AGENT_DISPLAY_OUT と $AGENT_CONTEXT_OUT という環境変数をセットします。
これらの環境変数にはファイルパスが入っており、スクリプト内でそのパスに対して書き込むことで出力先を制御できます。

環境変数 エージェントのコンテキストに含まれるか 用途
$AGENT_DISPLAY_OUT No ビルドログなど、コンテキストを膨らませたくない出力
$AGENT_CONTEXT_OUT Yes（agent_notes として） エージェントに確実に届けたいメッセージ

https://kiro.dev/docs/cli/reference/built-in-tools/#side-channels-for-wrapper-scripts

公式ドキュメントによると、$AGENT_CONTEXT_OUT に書き込んだ内容はツール結果の agent_notes フィールドとしてエージェントに渡されるとのこと。
$AGENT_DISPLAY_OUT に書き込んだ内容はエージェントのコンテキストには含まれません。

Lines written to $AGENT_CONTEXT_OUT surface in the tool result's agent_notes field, so the agent can read them alongside stdout and stderr. Lines written to $AGENT_DISPLAY_OUT only reach the TUI.

つまり、stdout に書いた内容と $AGENT_CONTEXT_OUT に書いた内容はどちらもエージェントが読めますが、$AGENT_DISPLAY_OUT に書いた内容だけはエージェントに渡りません。
大量のログを stdout に流すとコンテキストを消費してしまうので、ログは $AGENT_DISPLAY_OUT に逃がしてエージェントにはサマリーだけ渡す、という使い方ができます。

なお、これらの環境変数はエージェントが TUI 内でシェルコマンドを実行する場合にのみ設定されます。
通常のターミナルから直接スクリプトを実行した場合は環境変数が空なので、Side Channels への書き込みはスキップされます。

$ echo "AGENT_DISPLAY_OUT=${AGENT_DISPLAY_OUT:-not set}"
AGENT_DISPLAY_OUT: not set

以下のようなテスト用ラッパースクリプトを用意して、TUI 内でエージェントに実行させてみました。

test-side-channels.sh
#!/usr/bin/env bash
echo "=== Side Channels Test ==="
echo "AGENT_DISPLAY_OUT: ${AGENT_DISPLAY_OUT:-not set}"
echo "AGENT_CONTEXT_OUT: ${AGENT_CONTEXT_OUT:-not set}"

# AGENT_DISPLAY_OUT: エージェントのコンテキストには入らない
if [ -n "${AGENT_DISPLAY_OUT:-}" ]; then
  echo "[DISPLAY] Building module 1/3... done (2.1s)" > "$AGENT_DISPLAY_OUT"
  echo "[DISPLAY] Building module 2/3... done (1.8s)" > "$AGENT_DISPLAY_OUT"
  echo "[DISPLAY] Building module 3/3... done (3.2s)" > "$AGENT_DISPLAY_OUT"
  echo "[DISPLAY] Total build time: 7.1s" > "$AGENT_DISPLAY_OUT"
fi

# AGENT_CONTEXT_OUT: エージェントの agent_notes に入る
if [ -n "${AGENT_CONTEXT_OUT:-}" ]; then
  echo "Build succeeded. All 3 modules compiled without errors." > "$AGENT_CONTEXT_OUT"
fi

# 通常の stdout: エージェントのコンテキストに入る
echo "ok"

実行結果を見てみます。

9C640834-D933-431A-B04E-304DF261EC38.png

エージェントがスクリプトを実行すると、AGENT_DISPLAY_OUT と AGENT_CONTEXT_OUT にそれぞれファイルパスが設定されていることがわかります。
/var/folders/.../agent-display-out-....fifo と /var/folders/.../agent-context-out-....fifo のようなパスです。
スクリプト内でこのパスに echo "..." > "$AGENT_DISPLAY_OUT" のように書き込むことで、出力先を振り分けています。

実行後、エージェントが結果をまとめてくれました。
エージェントの応答を見ると、stdout に出力した内容と $AGENT_CONTEXT_OUT に書き込んだ「Build succeeded. All 3 modules compiled without errors.」には言及しています。
一方、$AGENT_DISPLAY_OUT に書き込んだ [DISPLAY] Building module 1/3... 等の行には一切触れていません。
$AGENT_DISPLAY_OUT に書き込んだ内容がエージェントのコンテキストから除外されていることが確認できました。

Side Channels を活用するには、$AGENT_DISPLAY_OUT や $AGENT_CONTEXT_OUT に書き込む処理をスクリプトに書いておく必要があります。
エージェントが直接実行する npm run build のようなコマンドは Side Channels を意識していないので、そのままでは stdout にすべて出力されます。
そこで、元のコマンドをラップして出力を振り分けるスクリプトを用意する形になります。
普段の使い方としては以下のようなパターンが考えられます。

  • ビルドコマンドのラッパー：詳細なビルドログは $AGENT_DISPLAY_OUT に流し、エージェントには「成功/失敗」と「エラー箇所のサマリー」だけ $AGENT_CONTEXT_OUT で伝える
  • テスト実行のラッパー：テスト全件の出力は $AGENT_DISPLAY_OUT に流し、失敗したテスト名だけ $AGENT_CONTEXT_OUT で伝える
  • デプロイスクリプトのラッパー：進捗ログは $AGENT_DISPLAY_OUT でユーザーに見せつつ、最終的なデプロイ結果だけエージェントに渡す

カスタムエージェントの hooks や toolsSettings でラッパースクリプトを指定しておけば、普段のチャットでは意識せずに Side Channels の恩恵を受けられます。
特にコンテキストウィンドウが逼迫しがちな長いセッションで効果がありそうです。

OAuth Client ID for MCP Servers について

MCP プロトコルの認証仕様では OAuth 2.1 が採用されています。
これは Kiro CLI に限らず MCP 標準の仕様で、HTTP ベースの MCP サーバーに接続する際の認証フローとして定義されています。

https://blog.modelcontextprotocol.io/posts/client_registration/

この仕様では、MCP クライアント（Kiro CLI や Claude Code など）が MCP サーバーに接続する際、認可サーバーにクライアント自身を登録する必要があります。
この登録を API 経由で自動的に行う仕組みが Dynamic Client Registration (DCR) です。
DCR に対応している認可サーバーであれば、ユーザーは Client ID を事前に用意しなくても接続できます。

しかし、本日時点で Slack や GitHub などのサービスは DCR に対応していません。
実際に Slack MCP サーバーに接続しようとすると「does not support dynamic client registration」というエラーが発生する問題が報告されています。

https://github.com/slackapi/slack-mcp-plugin/issues/7

DCR 非対応のサービスに接続するには、各サービスの開発者ポータルで OAuth App を事前に手動登録して Client ID を取得しておく必要があります。
これまで Kiro CLI にはその取得した Client ID を設定に書く場所がなかったため、DCR 非対応サービスの MCP サーバーには接続できない状態でした。

今回のアップデートで oauth.clientId フィールドが追加され、事前に取得した Client ID を設定できるようになりました。
DCR が失敗した場合にこの Client ID がフォールバックとして使われ、OAuth フローが完了するようになっています。

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "clientId": "your-slack-app-client-id",
        "oauthScopes": ["search:read", "channels:read"]
      }
    }
  }
}

https://kiro.dev/docs/cli/custom-agents/configuration-reference/#oauth-configuration

Pre-registered OAuth client ID used as a fallback when Dynamic Client Registration (DCR) fails. Required for services like Slack, GitHub, and Figma that don't support DCR and issue OAuth credentials through manual app registration.

DCR をサポートしているサービスであれば従来通り oauth.clientId なしで接続できるので、DCR 非対応サービス向けのフォールバック設定という位置づけです。

さいごに

本日は Kiro CLI 2.3.0 で追加された KIRO_HOME 環境変数、V2 TUI キーバインドのカスタマイズ、Agent Output Side Channels を確認してみました。

KIRO_HOME はグローバルエージェントやステアリングごと切り替わるので、仕事用と個人用とかエージェント構成を完全に分けたい場合に使えそうです。
Side Channels はラッパースクリプトを書く手間はありますが、ビルドログのような大量出力をエージェントのコンテキストから除外できるのは長いセッションで効いてきそうです。
OAuth Client ID の対応も、Slack MCP サーバーなどを使いたい場合にプロキシ不要で接続できるようになったのは嬉しいアップデートですね。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事

注目の記事
Kiro CLI に入門
川原征大
2025.11.24
Kiro CLIはぶっちゃけどんな場面で使えばいいか考えてみた
せーの
2026.02.19
[アップデート] Kiro CLI に実験的なリッチターミナル UI（TUI v2）が追加されたので使ってみた
いわさ
2026.03.22
[アップデート] Kiro CLI 2.0 でサブエージェントにタスク依存関係やエージェントモニターなどが追加されたので確認してみた
いわさ
2026.04.15