Grok Plugin Codex

grok-plugin-codex expone una CLI de Grok instalada localmente a Codex a través de un servidor MCP empaquetado en Node/TypeScript. Codex sigue siendo responsable del ámbito, el estado del espacio de trabajo, la verificación, git y el juicio final; Grok es una segunda superficie acotada.

La versión 0.3.0 es la versión actual. Normaliza el vocabulario de motivos de parada de Grok (end_turn y EndTurn son un mismo hecho), clasifica correctamente los tiempos de espera y el agotamiento de cuotas, establece por defecto las herramientas de envío en segundo plano con presupuestos de tiempo por tipo, devuelve un identificador de recuperación en cada resultado no completo, se niega a informar de un veredicto alcanzado sin una sola llamada a herramienta como una revisión completada y añade grok_finalize — la única forma de recuperar una respuesta ya existente en un solo turno y sin herramientas. Consulte CHANGELOG.md para conocer los cambios completos del contrato. La versión 0.2 introdujo la arquitectura de trabajador central privado y los sobres MCP tipados.

Repositorio: https://github.com/handong66/grok-plugin-codex Artículo: https://han-dong.link/en/work/grok-plugin-codex

Requisitos

• Node.js >=22

• npm

• macOS o Linux

• Soporte del mercado de plugins locales de Codex

• CLI de Grok instalada y autenticada

Verifique las tres capas de tiempo de ejecución por separado:

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

Un modelo listado no ha completado necesariamente una invocación real. grok_check preserva esa distinción.

Related MCP server: chatgpt-codex-local-mcp

Instalación

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

Inicie una nueva tarea de Codex después de la instalación o actualización. Las tareas existentes conservan la instantánea del servidor MCP y la habilidad con la que comenzaron. Si una nueva tarea de Codex Desktop ve la habilidad actualizada pero no las herramientas MCP actualizadas, reinicie Codex Desktop y cree otra tarea; el proceso de Desktop puede retener su registro MCP durante la reinstalación.

El paquete instalado contiene ambos:

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

Superficie de capacidades

• grok_check, grok_models: diagnóstico de CLI/capacidad, autenticación, derecho y modelo. authenticated y entitled son true, false o "unknown" — nunca null.

• grok_run, grok_continue: ejecución explícita de indicaciones y continuación de sesión conocida.

• grok_finalize: un turno, sin herramientas, respuesta completa: la recuperación para una ejecución con tiempo de espera agotado, límite de turnos alcanzado, cancelada o bloqueada por permisos.

• grok_rescue, grok_review, grok_adversarial_review: segundas pasadas de solo lectura forzadas, sin subagentes. Cada una necesita un target (o problem), para el cual también se acepta el nombre de la habilidad hermana prompt. grok_adversarial_review toma un threatModel opcional; los hallazgos fuera de él son solo consultivos y pueden no bloquear.

• grok_sessions, grok_export: inspección de sesiones del espacio de trabajo explícito y exportación a Markdown.

• grok_status, grok_result, grok_cancel: ciclo de vida privado de trabajos en segundo plano central solo por jobId. grok_status devuelve progreso ligero (textChars, eventCounts, lastEventAt, toolCallCount, deniedToolCalls) y toma un waitMs opcional (≤ 30 s) de espera del lado del servidor; grok_result pagina finalText con finalTextOffset / finalTextMaxChars.

El esquema actual de listTools de MCP es la autoridad para los argumentos exactos. La prueba de humo del repositorio bloquea la superficie publicada y rechaza la desviación.

Contrato de resultados

Las operaciones exitosas devuelven:

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

Los fallos de negocio establecen isError: true de MCP y devuelven:

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

Las violaciones del esquema de entrada son errores de herramienta generados por el SDK (isError: true) sin el sobre de negocio del plugin; los clientes deben inspeccionar el resultado resuelto de la herramienta en lugar de confiar solo en el rechazo de la promesa. Cada herramienta publica un esquema de salida, y el texto JSON manejado por el plugin refleja structuredContent.

Límites del espacio de trabajo y las indicaciones

Las operaciones del espacio de trabajo requieren cwd. El servidor canoniza los enlaces simbólicos y requiere que el directorio resuelto permanezca dentro de una raíz activa del espacio de trabajo de MCP. Las rutas privadas de Codex como ~/.codex están bloqueadas a menos que el usuario autorice explícitamente ese riesgo.

Las indicaciones se almacenan brevemente en archivos privados 0600 para que un trabajador desacoplado pueda sobrevivir a la salida del servidor MCP. El trabajador lee y elimina el archivo de almacenamiento antes de que Grok se ejecute, luego suministra la indicación a través de un FIFO 0600 dentro de un directorio aleatorio 0700. Grok recibe solo ese nombre de ruta privado a través de --prompt-file nativo; el lanzador lo desvincula tan pronto como Grok lo abre, antes de escribir cualquier byte de indicación. El texto de la indicación no se coloca en la lista de argumentos del proceso hijo ni en el registro del trabajo. GROK_BIN es la única configuración de ejecutable personalizado admitida y debe provenir del entorno MCP de confianza.

Trabajos en segundo plano

Los trabajos en segundo plano se ejecutan en un trabajador desacoplado y sobreviven a los reinicios del servidor MCP. El estado reside bajo:

1. $GROK_PLUGIN_STATE_DIR, cuando se configura explícitamente;

2. $XDG_STATE_HOME/grok-plugin-codex;

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

Un directorio de estado explícito debe ser disjunto de cada raíz activa del espacio de trabajo: ni dentro de una raíz ni un ancestro de una. Debe estar vacío, llevar la marca de propiedad del plugin o coincidir con el diseño estricto de trabajos previo a la marca privada; el plugin no reclamará ni hará chmod de un directorio compartido existente. Estas comprobaciones fallan de forma segura antes de crear o cambiar el estado local del repositorio.

Los directorios usan 0700; los registros, registros, archivos de almacenamiento de indicaciones, marcadores de cancelación, latidos y bloqueos entre procesos con token de propietario usan 0600. Las escrituras de registros son atómicas y el estado terminal es monótono. La cancelación se linealiza mediante un marcador consumido por el trabajador propietario. Cada grupo de procesos está liderado por un lanzador privado cuya identidad de comando incluye el ID del trabajo y un token de trabajo aleatorio; la reconciliación de trabajadores obsoletos termina un grupo persistido solo cuando los tres coinciden, y el lanzador elimina los descendientes residuales antes de salir.

Las herramientas de envío (grok_run, grok_review, grok_adversarial_review, grok_rescue) tienen por defecto background: true; grok_continue tiene por defecto primer plano. Guarde data.job.id, luego llame a las herramientas de trabajo con jobId. Una llamada en primer plano (background: false) bloquea durante un máximo de timeoutMs más un período de gracia de 10 s y luego devuelve foreground_wait_timeout con ese ID de trabajo. Un timeoutMs omitido tiene un valor predeterminado por tipo: run/continue 180000, review/rescue 240000, adversarial_review 300000 — y un valor explícito nunca se ajusta en ninguna dirección; ambos valores efectivos se devuelven como effectiveTimeoutMs / effectiveMaxTurns. El ritmo recomendado para un trabajo en segundo plano es un grok_status con waitMs, luego un grok_result, en lugar de un bucle de sondeo. Solo esta combinación es definitiva:

data.resultComplete === true

Internamente, la completitud también requiere texto final no vacío y un evento final normal, y — para grok_review y grok_adversarial_review — al menos una llamada a herramienta, ya que un veredicto de un revisor que no abrió nada es una opinión (no_evidence_review). Los tipos de solo lectura se ejecutan en modo plan, donde la ejecución de shell se rechaza automáticamente: incluya el diff o la salida del comando que la revisión necesita en el objetivo, y una ejecución que se canceló porque un comando de shell necesitaba aprobación se informa como permission_denied_headless en lugar de como un objetivo que era demasiado amplio. Los motivos de parada se normalizan sin distinción de mayúsculas y minúsculas ni separadores (end_turn y EndTurn son el mismo hecho), el valor sin procesar se conserva en outputSummary.stopReason, y los llamantes no deben hacer coincidencias de cadenas ellos mismos. Un final cancelado se devuelve como cancelled_output. Un motivo de parada no reconocido después de texto real se acepta con stopReasonRecognised: false más una advertencia en lugar de descartarse.

Cada resultado no completo lleva un identificador de recuperación — error.details.recovery en una llamada en primer plano fallida, data.recovery en grok_result — con la forma { jobId, grokSessionId, partialTextChars, suggested: { tool: "grok_finalize", args }, fallback: { tool: "grok_continue", args } }. El identificador se puede ejecutar tal cual: suggested es la recuperación de una llamada, y fallback es lo mismo expresado para un llamante que solo habla grok_continue (maxTurns: 1 más la indicación de grok_finalize). Ninguno pide una respuesta abreviada. El remedio para max_turns_reached y para una ejecución cancelada o con tiempo de espera agotado es grok_finalize con ese ID de trabajo, o la misma llamada manualmente: continúe la misma sesión con maxTurns: 1 y una indicación diciéndole a Grok que deje de usar herramientas y emita la respuesta final ahora. No reduzca el objetivo, aumente maxTurns ni vuelva a ejecutar la tarea: la respuesta parcial nunca se destruye, error.details.finalTextRef es el ID del trabajo, y grok_result devuelve el texto capturado completo independientemente de lo que diga resultComplete.

resultComplete explica el truncamiento por sí mismo: outputTruncated solo dice que la ventana de captura compartida se desbordó, que normalmente es eco de llamada a herramienta, mientras que textTruncated dice que se descartó texto de respuesta y es la bandera que veta la completitud. Las cargas útiles de herramientas demasiado grandes se eliden en el momento de la captura y las cargas útiles de available_commands se descartan; configure GROK_PLUGIN_RAW_CAPTURE=1 para mantener la secuencia del proveedor literalmente para el desarrollo del plugin.

Use data.finalText. Los estados parciales son solo de diagnóstico, y los registros de cola sin procesar por token se devuelven solo cuando se llama a grok_result con includeRawTail: true. El trabajador mantiene la respuesta en un libro mayor <id>.final.txt de solo anexión y los hechos de la secuencia en <id>.summary.json, por lo que grok_result responde desde ese libro mayor en lugar de volver a analizar la secuencia sin procesar, y grok_status lee el progreso del mismo archivo. Los artefactos de trabajo terminal se conservan durante siete días y se limpian oportunistamente.

Actualización desde 0.1

• Termine o cancele los trabajos en segundo plano de 0.1 antes de actualizar.

• 0.2 no escanea ni confía en registros antiguos de <workspace>/.grok-plugin-codex/jobs.

• Los directorios de espacio de trabajo antiguos no se eliminan automáticamente porque pertenecen al espacio de trabajo del usuario.

• Se eliminan la selección de ejecutable por llamada, los archivos de exportación seleccionados por el llamante, los objetivos de revisión implícitos y el cwd de control de trabajos.

Límite de privacidad

El plugin no copia el contexto oculto de Codex, mensajes de sistema/desarrollador, razonamiento, salida arbitraria de herramientas, secretos o credenciales en las indicaciones. No puede redactar texto sensible que un llamante proporcione explícitamente. Consulte docs/privacy.md.

Desarrollo

npm install
npm run check
git diff --check

Invocación autenticada opcional:

npm run smoke:live-grok

Los esquemas de tiempo de ejecución y las pruebas son la autoridad. Los archivos README/skill empaquetados son el contrato del usuario instalado; test/contract-drift.test.ts y la prueba de humo de MCP evitan que aparezcan argumentos eliminados o versiones no coincidentes.

Consulte docs/development.md y docs/verification.md.

Políticas del proyecto

• Política de Privacidad

• Términos de Uso

• Política de Seguridad

• Contribuir