grok-plugin-codex

Chino | English

Un plugin para usar Grok directamente en Codex.
Tú sigues hablando con Codex. Las revisiones, los bugs difíciles, las propuestas, el diseño, el seguimiento de PRs y la generación de documentos / imágenes / vídeos se delegan al Grok Build local.

No es un producto oficial de xAI / OpenAI. Versión actual 0.6.0. Apache-2.0. Derivado de stdevMac/grok-in-codex.

Qué es esto

Codex sigue siendo el capataz: tú le hablas, él descompone las tareas y vigila el progreso.
Este repositorio es solo una capa fina de plugin MCP; no sustituye a Codex ni incrusta el modelo de Grok en Codex. Llama al CLI grok que ya tienes instalado en tu máquina.

Útil para: añadir un segundo agente capaz de trabajar dentro de Codex; obtener una revisión estructurada antes de un merge; seguir el flujo «propuesta → diseño → implementación»; o usar las capacidades de imagen / vídeo / documento de Grok (que Codex no tiene).
No hace falta para: arreglos de una línea, renombrados o charlas que no tocan el repositorio.

Related MCP server: Grok-in-Codex

Qué puede hacer

Los trabajos de producto más grandes no deben meterse en un solo rescue gigante:

Los artefactos se guardan en el directorio del proyecto (se recomienda añadirlos a gitignore): .grok-plans/ .grok-designs/ .grok-reviews/ .grok-docs/ .grok-media/ .grok-workflows/.

Entorno

• Node.js 18.18+

• Grok Build CLI (grok) en el PATH; la ruta habitual es ~/.grok/bin/grok

• grok login

• Se recomienda Grok Build ≥ 1.0.5 (0.2.118 sigue arrancando; los flags concretos se activan según la detección de capacidades)

• gh solo es necesario si quieres publicar comentarios en PRs

Este plugin no trae modelo propio ni inicia sesión en Grok por ti.

Instalación

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

Abre una sesión nueva de Codex para que se carguen las herramientas MCP. Después:

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

O haz que Codex llame a grok_setup.

Codex puede arrancar el plugin desde la caché de instalación. Pasa la ruta real del proyecto a cwd en cada llamada a una herramienta para que las tareas y los artefactos caigan en ese repositorio:

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

Primeros pasos

Dile directamente a Codex:

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

Ejemplo de 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"

Resumen de herramientas

Parámetros de control para tareas largas: sandbox (workspace, read-only, strict, devbox, off; el alias antiguo workspace-write se normaliza a workspace), planMode / permissionMode, agent, noSubagents, memory / noMemory, allow / deny, disableWebSearch, forkSession, maxTurns.

Alineado con Grok CLI 1.0.x: si el CLI no tiene --check / --best-of-n, no se pasan a la fuerza. check=true se escribe en el prompt. Las tareas de escritura que solo leen / solo consultan durante muchas rondas sin escribir archivos se detienen por deriva de ejecución.

Notas de uso

Rescue — Escribible por defecto. readOnly=true solo depura. worktree=true modifica de forma más segura.

Plan / design / execute — Los artefactos van a .grok-plans/ y .grok-designs/. latest=true selecciona el diseño más reciente. dryRun=true es de solo lectura.

Review — Nunca aplica parches. Con postPending=true y un PR añadido, solo publica un comentario PENDING en GitHub si hay hallazgos.

Media — Los archivos se copian a .grok-media/ para mantener el contrato de ruta del proyecto.

Jobs — background=true devuelve un id de job. Varias tareas de Grok pueden ejecutarse a la vez. Haz seguimiento con grok_status / grok_result / grok_cancel.

Postura del CLI — Usa denylist (--disallowed-tools) en lugar de allowlist. Los medios, el dry-run / validate-only y el list de babysit son de solo lectura (sin yolo). Las revisiones usan --sandbox read-only por defecto y no quitan las herramientas de shell (Grok 1.0.x las necesita para producir resultados de tarea).

Variables de entorno

Directorio de estado por defecto: ~/.grok/codex-plugin/state/. No se comparte con el estado del plugin de Claude.

Control de tareas

• No hay bloqueo global de tarea única. Para tareas largas, prioriza background=true.

• El estado se transmite por el flujo de texto y el flujo de pensamiento; con solo tokens en blanco sigue mostrando running. El estado también registra la última herramienta usada y si se ha ejecutado alguna herramienta de escritura.

• Los resultados de plan priorizan la recolección de plan.md. Las tareas completadas guardan config, usage y artifacts (v3).

• Reaper: pid muerto y result.json completo → completed; pid muerto pero resultado truncado → failed (no se queda en running para siempre).

• El result.json en segundo plano se escribe de forma atómica (tmp + rename).

• El post-pending de PR también se ejecuta al completarse en segundo plano; diff vacío / diff demasiado grande falla de forma cerrada y los hallazgos se escriben en .grok-reviews/.

Desarrollo

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

Los números de versión en package.json, plugins/grok/.codex-plugin/plugin.json y .agents/plugins/marketplace.json deben coincidir.

Licencia

Apache-2.0. Consulta LICENSE y NOTICE.

Este proyecto deriva de stdevMac/grok-in-codex de stdevMac.