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도 시작 가능; 구체적인 flag는 기능 탐지 스위치에 따름)

• 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에서 파생됨.