Grok Plugin Codex

grok-plugin-codex는 번들로 제공되는 Node/TypeScript MCP 서버를 통해 로컬에 설치된 Grok CLI를 Codex에 노출합니다. Codex는 범위, 작업 공간 상태, 검증, git 및 최종 판단에 대한 책임을 유지하며, Grok은 제한된 보조 표면입니다.

현재 릴리스는 버전 0.3.0입니다. Grok 중단 이유 어휘(end_turn과 EndTurn은 동일한 사실)를 정규화하고, 시간 초과 및 할당량 소진을 올바르게 분류하며, 디스패치 도구를 종류별 시간 예산과 함께 기본적으로 백그라운드로 설정하고, 모든 비완료 결과에 복구 핸들을 반환하며, 단일 도구 호출 없이 도달한 판정을 완료된 검토로 보고하지 않으며, 이미 존재하는 답변을 복구하는 단일 턴, 도구 없는 방법인 grok_finalize를 추가합니다. 전체 계약 변경 사항은 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 설치 및 인증 완료

세 가지 런타임 계층을 별도로 확인하세요:

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: 단일 턴, 도구 없음, 완전한 답변 — 시간 초과, 턴 제한, 취소 또는 권한 차단된 실행을 위한 복구.

• 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에 포함하는 비공개 런처가 이끌며, 오래된 워커 조정은 세 가지가 모두 일치할 때만 지속된 그룹을 종료하고, 런처는 종료 전에 잔여 하위 프로세스를 제거합니다.

디스패치 도구(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로 반환됩니다. 백그라운드 작업에 권장되는 리듬은 폴링 루프 대신 하나의 waitMs가 있는 grok_status 후 하나의 grok_result입니다. 이 조합만이 최종적입니다:

data.resultComplete === true

내부적으로 완전성은 비어 있지 않은 최종 텍스트와 정상 종료 이벤트도 필요로 하며, grok_review 및 grok_adversarial_review의 경우 최소 하나의 도구 호출이 필요합니다. 아무것도 열지 않은 검토자의 판정은 의견(no_evidence_review)이기 때문입니다. 읽기 전용 종류는 계획 모드에서 실행되며, 셸 실행이 자동으로 거부됩니다. 검토에 필요한 diff 또는 명령 출력을 대상에 인라인으로 포함시키고, 셸 명령 승인이 필요하여 취소된 실행은 대상이 너무 넓었다는 대신 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는 단일 호출 복구이고, 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를 참조하세요.

프로젝트 정책

• 개인정보 보호정책

• 이용약관

• 보안 정책

• 기여하기