Stream Deck + の8キー、4ダイヤル、4つのタッチ領域を、Codexデスクトップアプリの操作盤として使うmacOS向けプラグインです。
Codex Microの公式仕様にある「6件のタスクを状態つきで追う」「承認・却下を手元で行う」という考え方に加え、CodexのModel、Reasoning、Speed、Accessを4つのダイヤルから設定できるよう、Stream Deck +の形に合わせて再配置しています。OpenAIまたはElgatoの公式製品ではなく、ローカル環境向けの独立実装です。
v0.4.12では、右下キーを専用のVoiceボタンに変更しました。1回押すとCodexの音声入力を開始し、もう一度押すと文字起こししたテキストを送信します。既存の押している間だけ録音するキー役割も、カスタム設定用に維持しています。詳しくはv0.4.12リリースノートを参照してください。
v0.4.13は、このVoice操作の安全性修正版です。Cmd+Kのコマンドパレットを音声開始に使わず、Codexの編集メニューと入力欄付近の音声ボタンだけを限定的に操作します。処理中の連打、録音中の別操作、キー消失時の状態残留も安全側で抑止します。詳しくはv0.4.13リリースノートを参照してください。
キーは上段左から右、次に下段左から右の順です。
| 位置 | 割り当て | 操作 |
|---|---|---|
| 上段 1〜4 | Agent 1〜4 | 最近更新されたCodexタスクを開く |
| 下段 1〜2 | Agent 5〜6 | 最近更新されたCodexタスクを開く |
| 下段 3 | Approve | 応答できる承認要求がある間だけ点灯し、その要求を承認する |
| 下段 4 | Voice | 1回目でCodexの音声入力を開始し、2回目で文字起こしして送信する |
ハードウェア上では、Agentキーをロボットアイコン、1〜6の番号、1行のタスク名で区別します。表示中の6キーは、それぞれ長いタスク名を100ミリ秒間隔・10ピクセル刻みで横へ流し、短い名前は静止表示します。右下の形つき状態アイコンも維持します。選択中の外枠明滅とApproveのチェックも変わりません。Voiceキーは待機中に白いマイクとTap to talk、録音中に青いマイクとListening…を表示します。
Voiceキーは1回目の押下で録音を開始し、キーを離しても録音を継続します。もう一度押すと、Codex自身の「文字起こしして送信する」を実行します。開始または停止の処理中に届いた追加押下はキューへ積まず無視します。録音中は停止に使うVoice操作以外のキー、ダイヤル回転、タッチ操作を実行しません。Declineは削除しておらず、任意キーのProperty Inspectorから引き続き選択できます。
Agentキーを1回押すと、そのタスクをバックグラウンドで選択します。350ミリ秒以内に2回押すと、Codexを前面に出して選択します。既定では直近6件を自動割り当てします。Stream Deckアプリでキーを選び、「最近のタスクを自動で割り当てる」をOFFにしてProperty Inspectorの「固定するタスクID」にIDを入れると固定割り当てもできます。自動割り当てをOFFにしたままタスクIDを空欄にすると、そのキーは意図的に未割り当てとなり、消灯状態を表示します。
各ダイヤルと、その真上にある200×100ピクセルのタッチ領域は1組のEncoderとして動きます。
| 左から | 設定 | 回して選べる候補 | 適用操作 |
|---|---|---|---|
| 1: Model | 使用モデル | ローカルのモデルキャッシュでvisibility=listのモデルをpriority順に表示 |
回転停止80ミリ秒後に自動適用 |
| 2: Reasoning | 推論レベル | 選択モデルが対応するLow、Medium、High、XHigh、Ultra（Maxは送信しない） | 回転停止80ミリ秒後に自動適用 |
| 3: Speed | 処理速度 | Standard、Fast | 回転停止80ミリ秒後に自動適用 |
| 4: Access | アクセス方針 | Ask、Delegate、Full、Custom | 回転停止80ミリ秒後に自動適用 |
4本すべて、回して止めるだけで適用します。再回転は前の80ミリ秒待機を取り消し、最後に止めた候補だけを適用します。
| ジェスチャー | 動作 |
|---|---|
| 回す | 候補を選ぶ。全4本とも回転停止80ミリ秒後に自動適用する。再回転は前の待機を取り消す。音声入力中は何も変更しない |
| ダイヤルを押す | 1回目はCodexの音声入力を開始。もう一度押すと文字起こしを完了し、そのテキストを送信する。開始と終了は別のダイヤルでもよい |
| タッチ領域をタップ | ディスク上の現在設定を再読込し、待機中の自動適用を中止する |
| タッチ領域を長押し | その項目を既定値へ戻して原子的に適用し、待機中の自動適用を中止する |
音声入力を開始すると、まだ実行されていない全ダイヤルの80ミリ秒待機を取り消します。録音中は通常のアイコンと値を隠し、4画面を1枚の800×100ピクセル表示として扱う波形へ切り替えます。マイク音量を取得できない場合は静かな補助アニメーションを表示し、終了すると通常表示へ戻ります。
Accessの候補は次の4段階です。
| 表示 | 意味 | 設定値 |
|---|---|---|
| Ask | workspace書込み、必要時は本人へ確認 | approval_policy=on-request、approvals_reviewer=user、permissions=:workspace |
| Delegate | workspace書込み、必要時は代理承認 | approval_policy=on-request、approvals_reviewer=guardian_subagent、permissions=:workspace |
| Full | フルアクセス、確認なし | approval_policy=never、approvals_reviewer=user、permissions=:danger-full-access |
| Custom | 現在のconfig.tomlを使う | configから解決したapproval・reviewer・sandboxPolicy |
Ask／Delegate／Fullはconfig.tomlの新規タスク既定値も更新します。Customだけはconfig.tomlを書き換えず、今の設定を追跡タスクへ送ります。選んだAccess modeはプラグインのグローバル設定に保存するため、Modelなどを変更してもCustomへ戻りません。旧Strict／Auto／Neverは読み込み互換だけを残し、通常候補には出ません。
タッチ領域の中央アイコンは、ModelがCPU、Reasoningが脳回路、Speedが速度計、Accessが盾とチェックです。アイコンの下には選択中または適用済みの値を1行で表示します。Accessもアンバーの候補表示中、80ミリ秒待つとFullを含めて自動適用します。v0.4.8以降の物理押下は設定の即時適用ではなく、4本共通の音声入力に使用します。
全Agentタスクへ同期して読み戻しまで一致した場合でも、Deck表示は選択中の値のまま保ちます。成功時の一時的なSynced表示は出しません。CustomはactivePermissionProfile=nullとsandboxも照合し、古いprofileの残留を成功扱いしません。一部または全件で同期または検証に失敗した場合は4秒間、アンバーで⚠ X/Nを表示します。追跡タスクがない場合だけ✓ Defaultです。Agentタスクの設定は現在実行中のターン途中では切り替わらず、次のターンから使われます。通常、Codexの再起動は必要ありません。
タッチストリップ上のスワイプは、Stream Deck本体がページ・プロファイル切替に使用します。Elgatoの公開プラグインAPIからスワイプイベントは渡されないため、このプラグインでは各領域のタップと長押しを使用します。
より詳しい対応関係は機能対応表を参照してください。
| 色 | コード | 状態アイコン | 意味 |
|---|---|---|---|
| 白 | #FFFFFF |
円と点 | アイドル |
| 青 | #304FFE |
回転を表す円弧 | Codexが作業中 |
| 緑 | #00FF4C |
円とチェック | 完了し、まだ確認していない更新がある |
| アンバー | #FF6D00 |
円と感嘆符 | 承認または回答が必要 |
| 赤 | #FF0033 |
警告の三角形 | エラー |
| 消灯 | #000000 |
斜線入りの円 | タスク未割り当て |
色はCodex Microの仕様と同じ意味にそろえています。色だけでなく形でも状態を区別できるため、色の見え方が異なる場合にも判別できます。選択中のAgentは外枠の明滅でも示します。ただし本プラグインはCodexデスクトップ内部の専用ハードウェア接続を使えないため、ローカルのタスク履歴から状態を推定します。
- macOS 13以降
- Stream Deck +
- Stream Deck 7.1以降
- Codexデスクトップアプリ（bundle ID
com.openai.codex） - ソースからビルドする場合はNode.js 24以降、npm、SwiftとmacOS SDKを含むXcode
Elgatoの現行CLI要件はStream Deck CLI公式ドキュメントで確認できます。
works.kawaii.codex-shortcuts-plugin.streamDeckPluginをダブルクリックします。- Stream Deckが表示するプラグインと同梱プロファイルの追加確認を承認します。
- Stream Deckアプリのプロファイル一覧から「Codex Shortcuts Plugin」を選びます。インストール時に現在のプロファイルを勝手に切り替えない設定です。
- Codexデスクトップアプリを起動します。
- 初めて音声入力またはショートカット系の操作を使うときにmacOSの許可画面が出たら、後述のアクセシビリティ設定を行います。
同梱プロファイルは8キーと4 Encoderをすべて事前配置しています。プロファイルの同梱形式についてはElgatoの公式ガイドを参照してください。
先に依存関係を用意します。Neverを使っていた可能性がある既存環境からv0.4.1へ更新する場合は、配備前に次の一回限りの移行を完了します。引数なしではdry-runになり、--applyを付けたときだけ新規タスクの既定値と重複のない直近6タスクの承認設定をAskへ変更します。これは実設定と実タスクを変更するため、結果を確認してから実行してください。
npm install
node scripts/migrate-approval-ask.mjs
node scripts/migrate-approval-ask.mjs --apply--applyが成功してから、検証と配布物作成へ進みます。
npm run check
npm run packnpm run checkは次の処理を順番に実行します。
- TypeScriptをビルドする
- Nodeテストを実行する
- 同梱プロファイルが生成元と一致するか検査する
- 依存パッケージを使わない独自バリデータで、manifest、画像、CodePath、Property Inspector、ZIP内部の8キー・4 Encoderを検査する
- Elgato公式CLIでもmanifestを検証する
成功すると、npm run packはdist-v0.4.13-final/に.streamDeckPluginインストーラを作成します。
開発中にソースフォルダを直接リンクする場合は、次を使用します。
npx streamdeck link works.kawaii.codex-shortcuts-plugin.sdPlugin
npx streamdeck restart works.kawaii.codex-shortcuts-pluginlinkはStream Deckのプラグイン領域からソースフォルダへの開発用リンクを作ります。正式な仕様はstreamdeck linkを参照してください。
タスクを開く操作はCodexのディープリンクを使用します。Approveと任意キーへ設定できるDeclineはCodexの承認要求へIPCで直接応答し、キーボード入力を送りません。カスタムショートカットは指定されたキー操作を使用します。通常のコマンドパレットに依存する追加キー役割は、v0.4.13では誤操作防止のため一時的に実行しません。音声入力の開始はCodexの編集メニュー項目を完全一致で選び、利用できない場合だけ入力欄付近の一意な音声ボタンを操作します。停止は「文字起こしして送信する」または挿入用の音声ボタンを操作します。4つの設定ダイヤルは~/.codex/config.tomlを読み書きし、Codexデスクトップが起動中なら追跡中のAgentタスクすべての次ターン用設定も更新します。
画面要素やショートカットの補完にはmacOSのアクセシビリティ権限が必要です。
- システム設定を開きます。
- 「プライバシーとセキュリティ」→「アクセシビリティ」を開きます。
- Stream Deck、またはmacOSが許可を求めたStream Deckのヘルパープロセスを有効にします。
- 「オートメーション」の確認が出た場合は、System EventsとCodexの操作を許可します。
- Stream Deckアプリを再起動します。
権限を与えない場合も状態表示、Agentキーのディープリンク、設定ダイヤルの回転、再読込、適用、既定値へのリセットは利用できますが、ダイヤル押下の音声入力とキーボードショートカットは失敗します。Property Inspectorの「Codexへの画面・キー操作を有効にする」をOFFにすると、これらのSystem Events操作だけを明示的に停止できます。許可を設定した後でONに戻してください。通常のコマンドパレット操作は権限にかかわらずv0.4.13では一時的に実行しません。
Stream DeckアプリでキーまたはEncoderを選ぶとProperty Inspectorが開きます。
- キーの「役割」: Agent、承認、却下、トグル式／押している間の音声入力、高速モード、レビューなどへ再割り当て
- ダイヤルの「役割」: Model、Reasoning、Speed、Accessへ再割り当て
- 「最近のタスクを自動で割り当てる」: Agentキーを直近タスクに追従させる
- 「固定するタスクID」: 自動割り当てをOFFにしたAgentキーを特定のタスクへ固定する。空欄なら未割り当て
- 「キー操作をカスタマイズ」: キー、およびダイヤルの左右回転へ
cmd+shift+r、escapeなどを指定。Model／Reasoning／Speed／Accessの物理押下は音声入力専用で変更不可 - 「状態の更新」: 1〜30秒。既定は2秒
- 「Codexへの画面・キー操作を有効にする」: System Events経由の音声入力ボタンとショートカット操作を許可・停止。設定ダイヤルの回転とタッチには影響しない
役割を選ぶと、押す・回す・タップ・長押しで何が起きるかを日本語で表示します。承認と却下には誤操作防止の注意、入力欄には形式エラー、画面上部には保存状態、画面下部にはStream Deckとの接続状態を表示します。
カスタムキー操作は、対象コントロールの対応するキー／回転操作を置き換えます。設定ダイヤルの物理押下による音声入力は置き換えません。まず既定レイアウトで動作確認してから変更してください。
Agentキーを別の役割へ変更した場合や、そのキーがプロファイル／ページから外れた場合は、以前のAgent枠と固定タスクIDを同期対象から直ちに解除します。
プラグインは外部サーバーへ通信せず、APIキーやCodexの認証情報を読みません。状態表示のために、次のローカルデータを読み取り専用で参照します。
~/.codex/state_5.sqlite: 直近のユーザー所有タスクとrolloutファイルの場所~/.codex/sqlite/codex-dev.db: 未読情報（存在する場合）~/.codex/sessions/以下の参照先JSONL: 作業開始、完了、承認待ち、エラーの推定
Model、Reasoning、Speed、Ask／Delegate／Fullを適用するときだけ、~/.codex/config.tomlを読み書きします。Customは現在値を読むだけです。保存は一時ファイルを経由した原子的な置き換えで行います。Codexデスクトップが起動中は、同じMac上の所有者限定Unixソケット（~/.codex/ipc/ipc.sock）への常設接続で、現在follow中のタスクへ同じpatchの即時反映を先に開始し、承認要求の受信・応答を行います。次ターン設定の永続化は、ChatGPT／Codexアプリ同梱のCodex App Serverをその同期batch中だけ1回起動し、各exact ID内ではthread/resume→thread/settings/update→読み戻しの順を保ったまま、対象タスク間だけ並列に行います。Desktop IPCの失敗は永続化成功を妨げず、完了・失敗にかかわらず必ず停止します。Codexのデータベースやrolloutファイルを直接書き換えることはありません。
Agentキーはタスク名を表示しますが、タスクIDは表示しません。表示中の6キーは長い名前をそれぞれ100ミリ秒間隔・10ピクセル刻みで横へ流し、短い名前は静止表示します。選択中の外枠明滅は従来どおりです。プラグイン設定と「確認済み」のローカル状態は、Stream Deckの設定保存機能に書き込みます。Codexのデータベースやrolloutファイルには書き込みません。
音声機能はCodexの音声入力を起動します。録音中の波形表示を補助するため、このプラグイン同梱のローカルヘルパーはマイク音声からRMS音量だけを計算します。音声データは保存も外部送信もせず、音声入力終了時にヘルパーも停止します。初回だけmacOSからマイク使用の許可を求められる場合があります。ヘルパーのマイク許可を拒否しても、Codex自身の録音・文字起こし・送信には影響しません。
操作に失敗した場合は、キーまたはダイヤルの役割とイベント種別、短いエラー理由をStream Deckのプラグインログへ記録します。ログへ出す前に、タスクID、タスクURL、ユーザーフォルダのパス、複数行のプロセス出力を除去します。タスク本文やタイトルは記録しません。
- Codexデスクトップとのタスク設定連携は、同じユーザーで起動中のCodexへ接続するローカル経路を利用します。公開互換APIではないため、Codex更新後に一時的に利用できなくなる可能性があります。その場合も新規タスク用の既定値は
~/.codex/config.tomlへ保存し、Deckへ⚠ 0/Nを表示します。 - CodexのローカルDB形式と日本語コマンド名も公開互換APIではありません。Codex更新後に状態表示やUI補完が一時的に動かなくなる可能性があります。
- 自動割り当ては「直近6件」と「キーごとの固定タスクID」に対応します。Codex Microの「Pinned優先」「Priority順」の自動モードは未実装です。
- ApproveとDeclineは、コマンド実行またはファイル変更の実承認待ちがある間だけ点灯し、Codexデスクトップの正規IPCメソッドで要求IDへ直接応答します。質問だけの場合はAgentキーがアンバーでもApprove／Declineは消灯し、Codex側で回答します。複数タスクに要求がある場合は明示的に選択したAgentを最優先し、未選択なら現在表示中の一意な対象を使います。それでも決まらない場合や、同じタスクに複数の実承認要求がある場合は推測せずCodex側での操作を求めます。実行中の重複操作と同じ要求への2重応答も拒否します。
- キーへ割り当てるFast、Plan、Fork、Skills、Reviewなど、通常のコマンドパレットに依存する追加操作は、誤ってチャット入力欄へ文字やReturnを送らないようv0.4.13では一時的にfail-closedとなり、実行せずエラーを返します。
- 音声入力の開始はCodexの編集メニュー、フォールバックと停止は入力欄付近の英語・日本語アクセシビリティラベルへ完全一致して操作します。Codex更新でメニュー名、ボタン名、画面構造が変わると、一時的に開始または送信できなくなる可能性があります。
- 設定ダイヤルは選択した値を
~/.codex/config.tomlへ保存した後（Customを除く）、Agent 1〜6の各論理枠で解決した最大6タスクを重複排除して同期します。自動枠は対応する直近タスク、固定枠は指定ID、未割り当て枠は対象なしです。固定枠が同じ位置の自動タスクを置き換えるため、両方を足して7件以上へ誤同期しません。1項目だけでなく、保存済みのModel、Reasoning、Speed、Accessを完全な組として送り、古いタスク固有設定を残しません。現在実行中のターン途中は変更しません。 - Stream Deck SDKはタッチストリップのスワイプをプラグインへ公開しません。スワイプはStream Deck本体のページ・プロファイル切替として残ります。
- Codex Micro固有のバッテリー表示、専用ライトアニメーション、追加ハードウェアレイヤーは再現しません。Stream Deckの明るさやスリープはStream Deckアプリで管理します。
Codex App Serverの公式仕様を、全同期対象の次ターン設定を永続化する正規経路に使います。1つの同期batchごとにexperimentalApiを有効にして1プロセスを起動し、各exact ID内ではresume、完全設定の送信、読み戻し検証を順に行い、異なるタスク間だけ並列にします。常設Desktop followerの更新はfollow中タスクへの即時反映を先に開始しますが、成功件数はApp Serverで永続化できた件数を基準にします。batchは完了前にDesktop更新も必ず待つため、古いpatchが後から新しいダイヤル操作を上書きしません。既に実行中のターンを途中変更する機能ではありません。タスクの状態表示は引き続きローカルDBとrollout、および常設Desktop followerから推定します。
まずProperty Inspectorで「最近のタスクを自動で割り当てる」を確認します。OFFで「固定するタスクID」が空欄なら、未割り当て表示は正常です。自動割り当てがONの場合は、Codexでユーザー所有タスクを1件以上作り、Stream Deckを再起動してください。このプラグインは内部の承認レビュアーやサブエージェントを除外し、通常のユーザータスクだけを割り当てます。Codex更新直後にDB形式が変わった場合は、タスクIDを固定して切り分けできます。
Codexが起動していることと、macOSのアクセシビリティ・オートメーション権限を確認します。権限変更後はStream Deckを再起動してください。追加キー役割だけが失敗する場合は、Codexの表示言語またはコマンド名変更の可能性があります。
成功時は選択中の値がそのまま残り、各タスクの次のターンから反映されます。いま既に実行中のターンや、ちょうど返答を生成している途中のターンはその場では切り替わりません。⚠ X/Nなら一部または全部のタスクで失敗したため、Codexが起動していることを確認して同じ値を再適用します。全件失敗は⚠ 0/Nです。✓ Defaultは追跡タスクがなく新規タスクの既定値だけを保存した状態です。どの場合も新規タスクの既定値は保存済みで、通常はCodexの再起動は不要です。
Codexを開き、macOSのアクセシビリティ・オートメーション権限と、Property Inspectorの「Codexへの画面・キー操作を有効にする」を確認します。Codex自身のマイク権限が無効な場合は「システム設定」→「プライバシーとセキュリティ」→「マイク」も確認します。録音中は波形表示になり、ダイヤル回転は意図的に無効です。もう一度どれかの設定ダイヤルを押すと、Codex自身が文字起こしと送信を行います。
更新は既定で2秒間隔です。少し待っても変わらない場合は、Codexで対象タスクを開き直し、Property Inspectorの「状態の更新」を確認してください。状態は公式ハードウェア接続ではなくrolloutイベントからの推定です。
Stream Deckのプロファイル管理画面で「Codex Shortcuts Plugin」を探します。見つからない場合は、プラグインフォルダ内のprofiles/Codex Shortcuts Plugin.streamDeckProfileを手動で開いてインポートできます。現在のプロファイルは自動で置き換えません。
開発用リンクは、プロジェクトディレクトリで次を実行すると解除できます。ソースフォルダは削除されません。
npx streamdeck unlink works.kawaii.codex-shortcuts-plugin通常インストールしたプラグインは、Stream Deckアプリのプラグイン管理画面から「Codex Shortcuts Plugin」をアンインストールします。同梱プロファイルが残る場合があります。不要であることを確認してから、プロファイル管理画面で別途削除してください。
- Codex Micro
- Codex Commands
- Codex App Server
- OpenAI Supply Co. / Work Louder
- Stream Deck SDK
- Dials & Touch Strip
- Bundled Profiles
- Stream Deck CLI
Codex、ChatGPT、Codex MicroはOpenAIの名称です。Stream DeckはElgatoの名称です。このリポジトリは両社から承認・配布された公式プラグインではありません。