Grok Plugin Codex

grok-plugin-codex は、バンドルされた Node/TypeScript MCP サーバーを通じて、ローカルにインストールされた Grok CLI を Codex に公開します。Codex は引き続きスコープ、ワークスペースの状態、検証、git、最終判断を担当し、Grok は制限付きの第二の表面として機能します。

現在のリリースはバージョン 0.3.0 です。Grok の停止理由語彙（end_turn と EndTurn は同一の事実）を正規化し、タイムアウトとクォータ枯渇を正しく分類し、ディスパッチツールをデフォルトでバックグラウンド（種類ごとに時間予算付き）に設定し、不完全な結果ごとにリカバリハンドルを返し、ツール呼び出しを一度も行わずに到達した判定を完了したレビューとして報告することを拒否し、さらに grok_finalize（既に存在する回答を回復するための1ターン、ツール不要の方法）を追加します。完全な契約変更については CHANGELOG.md を参照してください。バージョン 0.2 では、プライベートな中央ワーカーアーキテクチャと型付き MCP エンベロープが導入されました。

リポジトリ: https://github.com/handong66/grok-plugin-codex 解説記事: https://han-dong.link/en/work/grok-plugin-codex

要件

• Node.js >=22

• npm

• macOS または Linux

• Codex ローカルプラグインマーケットプレイスのサポート

• Grok CLI がインストールされ、認証済みであること

3つのランタイムレイヤーを個別に確認してください:

grok --version   # CLI can be discovered
grok --help      # installed flags/capabilities
grok models      # authentication and model listing

リストされたモデルが実際の呼び出しを完了したとは限りません。grok_check はその区別を保持します。

Related MCP server: chatgpt-codex-local-mcp

インストール

npm install
npm run check
codex plugin marketplace add .
codex plugin add grok-plugin-codex --marketplace grok-plugin-codex

インストールまたはアップグレード後は、新しい Codex タスクを開始してください。既存のタスクは、開始時に使用していた MCP サーバーとスキルスナップショットを保持します。新しい Codex Desktop タスクが更新されたスキルを認識しても、更新された MCP ツールを認識しない場合は、Codex Desktop を再起動して別のタスクを作成してください。Desktop プロセスは再インストール後も MCP レジストリを保持する可能性があります。

インストールされたバンドルには以下が含まれます:

plugins/grok-plugin-codex/dist/server.js
plugins/grok-plugin-codex/dist/job-worker.js

機能面

• grok_check, grok_models: CLI/機能、認証、権限、モデルの診断。authenticated と entitled は true、false、または "unknown" のいずれかであり、null になることはありません。

• grok_run, grok_continue: 明示的なプロンプト実行と既知のセッションの継続。

• grok_finalize: 1ターン、ツールなし、完全な回答 — タイムアウト、ターン制限、キャンセル、または権限ブロックされた実行のためのリカバリ。

• grok_rescue, grok_review, grok_adversarial_review: 強制読み取り専用、サブエージェントなしのセカンドパス。それぞれに target（または problem）が必要で、兄弟プラグインの名前 prompt も受け入れます。grok_adversarial_review はオプションの threatModel を受け取り、それ以外の所見は参考情報であり、ブロックしない場合があります。

• grok_sessions, grok_export: 明示的ワークスペースのセッション検査と Markdown エクスポート。

• grok_status, grok_result, grok_cancel: プライベートな中央バックグラウンドジョブのライフサイクル。jobId のみで操作します。grok_status は安価な進捗（textChars、eventCounts、lastEventAt、toolCallCount、deniedToolCalls）を返し、オプションの waitMs（≤ 30 秒）サーバー側待機を受け付けます。grok_result は finalTextOffset / finalTextMaxChars で finalText をページングします。

正確な引数については、現在の MCP listTools スキーマが信頼できる情報源です。リポジトリのスモークテストは公開された表面をロックし、ドリフトを拒否します。

結果契約

成功した操作は以下を返します:

{ "ok": true, "data": {}, "error": null, "warnings": [] }

ビジネス上の失敗は MCP isError: true を設定し、以下を返します:

{
  "ok": false,
  "data": null,
  "error": { "code": "typed_code", "message": "actionable message", "retryable": false },
  "warnings": []
}

入力スキーマ違反は、プラグインのビジネスエンベロープなしで SDK 生成のツールエラー（isError: true）となります。クライアントはプロミス拒否のみに依存するのではなく、解決されたツール結果を検査する必要があります。すべてのツールは出力スキーマを公開し、プラグインが処理した JSON テキストは structuredContent を反映します。

ワークスペースとプロンプトの境界

ワークスペース操作には cwd が必要です。サーバーはシンボリックリンクを正規化し、解決されたディレクトリがアクティブな MCP ワークスペースルート内に留まることを要求します。~/.codex などのプライベートな Codex パスは、ユーザーが明示的にそのリスクを承認しない限りブロックされます。

プロンプトは、デタッチされたワーカーが MCP サーバーの終了後も存続できるよう、プライベートな 0600 ファイルに一時的にステージングされます。ワーカーは Grok の実行前にステージングファイルを読み取り削除し、ランダムな 0700 ディレクトリ内の 0600 FIFO を介してプロンプトを提供します。Grok はネイティブの --prompt-file を通じてそのプライベートなパス名のみを受け取ります。ランチャーは Grok がファイルを開くとすぐに、プロンプトバイトを書き込む前にリンクを解除します。プロンプトテキストは子プロセスの引数リストやジョブレコードには配置されません。GROK_BIN はサポートされている唯一のカスタム実行可能ファイル設定であり、信頼された MCP 環境からのものでなければなりません。

バックグラウンドジョブ

バックグラウンドジョブはデタッチされたワーカーで実行され、MCP サーバーの再起動後も存続します。状態は以下の場所に保存されます:

1. $GROK_PLUGIN_STATE_DIR（明示的に設定されている場合）

2. $XDG_STATE_HOME/grok-plugin-codex

3. ~/.local/state/grok-plugin-codex

明示的な状態ディレクトリは、アクティブなすべてのワークスペースルートと互いに素でなければなりません。つまり、ルートの内部でも祖先でもあってはなりません。空であるか、プラグインの所有権マーカーを持っているか、厳格なプライベート事前マーカージョブレイアウトと一致する必要があります。プラグインは既存の共有ディレクトリを主張したり chmod したりしません。これらのチェックは、リポジトリローカルの状態を作成または変更する前に、失敗時にクローズされます。

ディレクトリは 0700 を使用し、レコード、ログ、プロンプトステージングファイル、キャンセルマーカー、ハートビート、および所有権トークンのプロセス間ロックは 0600 を使用します。レコードの書き込みはアトミックであり、終了ステータスは単調です。キャンセルは、所有ワーカーによって消費されるマーカーによって線形化されます。各プロセスグループは、コマンド ID にジョブ ID とランダムなジョブトークンを含むプライベートランチャーによって主導されます。古いワーカーの調整は、3つすべてが一致する場合にのみ永続化されたグループを終了し、ランチャーは終了前に残りの子孫を削除します。

ディスパッチツール（grok_run、grok_review、grok_adversarial_review、grok_rescue）はデフォルトで background: true になります。grok_continue はデフォルトでフォアグラウンドです。data.job.id を保存し、jobId を使用してジョブツールを呼び出します。フォアグラウンド呼び出し（background: false）は、最大 timeoutMs に 10 秒の猶予を加えた時間ブロックし、その後 foreground_wait_timeout とそのジョブ ID を返します。timeoutMs が省略された場合のデフォルトは種類ごとに異なります — run/continue は 180000、review/rescue は 240000、adversarial_review は 300000 — 明示的な値はどちらの方向にもクランプされません。両方の有効値は effectiveTimeoutMs / effectiveMaxTurns として返されます。バックグラウンドジョブの推奨リズムは、1回の grok_status（waitMs 付き）、次に1回の grok_result であり、ポーリングループではありません。この組み合わせのみが最終的です:

data.resultComplete === true

内部的には、完全性には空でない最終テキストと通常の終了イベントも必要であり、grok_review および grok_adversarial_review の場合は少なくとも1回のツール呼び出しが必要です。なぜなら、何も開かなかったレビューアからの判定は意見（no_evidence_review）だからです。読み取り専用の種類は計画モードで実行され、シェル実行は自動的に拒否されます。レビューに必要な差分やコマンド出力をターゲットにインライン化してください。シェルコマンドの承認が必要なためにキャンセルされた実行は、ターゲットが広すぎるのではなく、permission_denied_headless として報告されます。停止理由は大文字小文字と区切り文字に依存せずに正規化され（end_turn と EndTurn は同一の事実）、生の値は outputSummary.stopReason に保持され、呼び出し元は自分で文字列マッチングを行ってはなりません。キャンセルされた終了は cancelled_output として返されます。実際のテキストの後に認識されない停止理由があった場合は、破棄される代わりに stopReasonRecognised: false と警告付きで受け入れられます。

不完全な結果にはすべてリカバリハンドルが付属します — 失敗したフォアグラウンド呼び出しの場合は error.details.recovery、grok_result の場合は data.recovery — 形状は { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } } です。ハンドルはそのまま実行可能です。suggested は1回の呼び出しによるリカバリであり、fallback は grok_continue のみを話す呼び出し元のために同じことを詳細に示したものです（maxTurns: 1 と grok_finalize プロンプト付き）。どちらも短縮された回答を要求しません。max_turns_reached およびキャンセルまたはタイムアウトした実行の対処法は、そのジョブ ID を使用した grok_finalize、または手動での同じ呼び出しです。同じセッションを maxTurns: 1 で継続し、Grok にツールの使用を停止して今すぐ最終回答を出力するよう指示するプロンプトを送ります。ターゲットを狭めたり、maxTurns を増やしたり、タスクを再実行したりしないでください。部分的な回答は決して破棄されず、error.details.finalTextRef はジョブ ID であり、grok_result は resultComplete の値に関係なく、キャプチャされた完全なテキストを返します。

resultComplete はそれ自体で切り詰めを考慮します。outputTruncated は共有キャプチャウィンドウがオーバーフローしたことのみを示し（通常はツール呼び出しのエコー）、textTruncated は回答テキストがドロップされたことを示し、完全性を無効にするフラグです。過大なツールペイロードはキャプチャ時に省略され、available_commands ペイロードはドロップされます。プラグイン開発のためにベンダーストリームをそのまま保持するには、GROK_PLUGIN_RAW_CAPTURE=1 を設定します。

data.finalText を使用してください。部分的な状態は診断のみであり、生のトークン単位のログ末尾は grok_result が includeRawTail: true で呼び出された場合にのみ返されます。ワーカーは回答を追記専用の <id>.final.txt 台帳に、ストリームの事実を <id>.summary.json に保持するため、grok_result は生のストリームを再解析する代わりにその台帳から回答し、grok_status は同じファイルから進捗を読み取ります。終了したジョブのアーティファクトは7日間保持され、日和見的にクリーンアップされます。

0.1 からのアップグレード

• アップグレード前に 0.1 のバックグラウンドジョブを完了またはキャンセルしてください。

• 0.2 は古い <workspace>/.grok-plugin-codex/jobs レコードをスキャンしたり信頼したりしません。

• 古いワークスペースディレクトリはユーザーのワークスペースに属するため、自動的には削除されません。

• 呼び出しごとの実行可能ファイル選択、呼び出し元が選択したエクスポートファイル、暗黙のレビューターゲット、およびジョブ制御の cwd は削除されました。

プライバシー境界

プラグインは、非表示の Codex コンテキスト、システム/開発者メッセージ、推論、任意のツール出力、シークレット、または資格情報をプロンプトにコピーしません。呼び出し元が明示的に提供した機密テキストを編集することはできません。docs/privacy.md を参照してください。

開発

npm install
npm run check
git diff --check

オプションの認証付き呼び出し:

npm run smoke:live-grok

ランタイムスキーマとテストが信頼できる情報源です。バンドルされた README/スキルファイルはインストールされたユーザー契約です。test/contract-drift.test.ts と MCP スモークテストにより、削除された引数や不一致のバージョンが再出現するのを防ぎます。

docs/development.md および docs/verification.md を参照してください。

プロジェクトポリシー

• プライバシーポリシー

• 利用規約

• セキュリティポリシー

• コントリビューション