grok-plugin-codex

中文 | English

Codex の中で Grok を直接使えるプラグイン。
人間は引き続き Codex と話す。レビュー、ハードバグ修正、設計提案、設計書作成、PR 監視、ドキュメント / 画像 / 動画生成は、ローカルの Grok Build に任せる。

xAI / OpenAI の公式製品ではない。現在のバージョンは 0.6.0。Apache-2.0。stdevMac/grok-in-codex から派生。

これは何か

Codex は引き続き現場監督の役割：あなたが Codex に話しかけ、Codex がタスクを分解して進捗を管理する。
このリポジトリはごく薄い MCP プラグインに過ぎず、Codex を置き換えるものではないし、Grok モデルを Codex に埋め込むものでもない。呼び出すのは、あなたのマシンに既にインストールされている grok CLI。

向いている用途： Codex の中にもう一つ働けるセカンドエージェントを追加したい；マージ前に構造化レビューが欲しい；「設計 → 実装 → 実行」の流れで進めたい；あるいは Grok の画像 / 動画 / ドキュメント生成機能（Codex にはない）を使いたい。
使う必要がない場合： 一行で直せる修正、リネーム、あるいはリポジトリに一切触れない雑談。

Related MCP server: Grok-in-Codex

できること

大きなプロダクト作業を一回の巨大な rescue に詰め込まないこと：

成果物はプロジェクトディレクトリに保存される（gitignore 推奨）：.grok-plans/ .grok-designs/ .grok-reviews/ .grok-docs/ .grok-media/ .grok-workflows/。

環境

• Node.js 18.18+

• Grok Build CLI（grok）が PATH 上にあること。一般的なパスは ~/.grok/bin/grok

• grok login

• Grok Build は ≥ 1.0.5 を推奨（0.2.118 でも起動は可能。具体的なフラグは機能検出スイッチによる）

• PR にコメントを投稿する場合のみ gh が必要

このプラグインはモデルを内蔵しておらず、Grok へのログインを代行もしない。

インストール

codex plugin marketplace add /path/to/grok-plugin-codex/.agents/plugins
codex plugin add grok@grok-plugin-codex

新しい Codex セッションを開くと MCP ツールが読み込まれる。その後：

node plugins/grok/scripts/grok-companion.mjs setup

または Codex に grok_setup を呼び出させる。

Codex はインストールキャッシュからプラグインを起動することがある。ツールを呼び出すたびに実際のプロジェクトパスを cwd として渡せば、タスクと成果物がそのリポジトリに保存される：

grok_review cwd="/path/to/project" base=main
grok_status cwd="/path/to/project" json=true

使い始める

Codex で直接こう言う：

让 Grok 对照 main 评审这个分支。
用 Grok 规划一次鉴权重写。
让 Grok 出一份设计文档，然后 dry-run 执行最新方案。
给重试重构开一个后台 Grok rescue。
用 Grok 生成一张 16:9 发布 banner。
看看 Grok 任务状态。

MCP の例：

grok_plan prompt="plan the auth rewrite" background=true
grok_design prompt="design multi-tenant billing" background=true
grok_execute_plan latest=true dryRun=true
grok_workflow action=list
grok_review base=main focus="auth, data loss, and race conditions"
grok_rescue prompt="investigate why npm test is failing" background=true
grok_babysit action=list
grok_document type=pdf prompt="one-pager for the launch"
grok_image aspect="16:9" prompt="Dark developer-tool launch banner"
grok_video image="./.grok-media/image/hero.png" duration="6" prompt="gentle camera push-in"
grok_status
grok_result jobId="plan-abc123"

ツール一覧

長時間タスクの制御パラメータ：sandbox（workspace、read-only、strict、devbox、off；旧エイリアス workspace-write は workspace に正規化される）、planMode / permissionMode、agent、noSubagents、memory / noMemory、allow / deny、disableWebSearch、forkSession、maxTurns。

Grok CLI 1.0.x に合わせる：CLI に --check / --best-of-n がない場合はハードコードで渡さない。check=true は prompt に書き込まれる。読み取り専用 / 多数のターンを実行してもファイルを書かない書き込みタスクは、実行ドリフトとして停止する。

使い方のポイント

Rescue — デフォルトで書き込み可。readOnly=true は調査のみ。worktree=true でより安全に変更。

Plan / design / execute — 成果物は .grok-plans/ と .grok-designs/ に保存。latest=true で最新の設計を選択。dryRun=true は読み取り専用。

Review — パッチは一切適用しない。postPending=true を PR に付けると、発見があった場合のみ PENDING GitHub コメントを投稿。

Media — ファイルは .grok-media/ にコピーされ、プロジェクトパス契約の範囲内に保たれる。

Jobs — background=true で job id が返る。複数の Grok タスクを同時に実行できる。grok_status / grok_result / grok_cancel で追跡。

CLI の姿勢 — allowlist ではなく denylist（--disallowed-tools）を使う。メディア、dry-run / validate-only、babysit の list はすべて読み取り専用（yolo は付けない）。レビューはデフォルトで --sandbox read-only で、shell ツールは外さない（Grok 1.0.x がタスク結果を生成するために必要）。

環境変数

デフォルトの状態ディレクトリ：~/.grok/codex-plugin/state/。Claude プラグインの状態とは共有しない。

タスク制御

• グローバルな単一タスクロックはない。長時間タスクは background=true を優先。

• 状態はテキストストリームと thought ストリームに追従。空白トークンのみの場合も running を表示。状態は直近のツールと、書き込みツールを実行したかどうかも記録。

• Plan 結果は plan.md を優先して回収。完了したタスクは config、usage、artifacts（v3）を保存。

• Reaper：pid が死んでいて result.json が完全 → completed；pid が死んでいるが結果が途中で切れている → failed（永遠に running のままにはならない）。

• バックグラウンドの result.json はアトミック書き込み（tmp + rename）。

• PR post-pending はバックグラウンド完了時にも実行。空 diff / 大きすぎる diff は fail closed し、発見は .grok-reviews/ に書き込まれる。

開発

npm test
node plugins/grok/scripts/grok-companion.mjs setup --json
node plugins/grok/mcp/server.mjs   # stdio NDJSON MCP server

package.json、plugins/grok/.codex-plugin/plugin.json、.agents/plugins/marketplace.json のバージョン番号は一致している必要がある。

ライセンス

Apache-2.0。LICENSE と NOTICE を参照。

このプロジェクトは stdevMac の stdevMac/grok-in-codex から派生したものである。