Codex Cursor Subagent Plugin

Complemento de Subagente Cursor para Codex y Claude Code

Usa Cursor Agent como un subagente interactivo desde Codex o Claude Code. Delega investigación de código, revisiones, planificación e implementación sin mover manualmente indicaciones y resultados entre aplicaciones.

El complemento inicia tu Cursor Agent instalado a través de ACP y expone su sesión interactiva mediante MCP. Puedes seguir el progreso, responder preguntas, revisar planes y continuar con tareas de seguimiento.

Contenido

• Demo
• Requisitos
• Configuración de Cursor Agent
• Instalación en Codex
• Instalación en Claude Code
• Uso
• Permisos y alcance
• Desarrollo

Demo

Delegar una tarea a Cursor desde Codex y luego reanudar la sesión de ACP para una solicitud de seguimiento:

Requisitos

• tiempo de ejecución e instalación portátil: Node.js 18+;
• Cursor Agent (cursor-agent) instalado y autenticado antes de usar el complemento (consulta Configuración de Cursor Agent a continuación);
• Codex con soporte local de complementos/MCP, o Claude Code con soporte de complementos.

Configuración de Cursor Agent

Instalar la CLI

El complemento no instala Cursor Agent ni te inicia sesión. Instálalo y autentícalo bajo el mismo usuario del sistema operativo y en el entorno donde se ejecuta Codex o Claude Code. Sigue la guía oficial de instalación de la CLI de Cursor. En macOS, Linux o WSL:

curl https://cursor.com/install -fsS | bash
export PATH="$HOME/.local/bin:$PATH"
cursor-agent --version

Mantén ~/.local/bin en el PATH de la aplicación anfitriona, o establece CURSOR_AGENT_COMMAND en la ruta absoluta del ejecutable de Agent. El instalador proporciona la CLI actual. El complemento se ha probado con Cursor Agent 2026.08.25-3e8eec8. Se espera que las versiones más nuevas funcionen si conservan la interfaz ACP requerida, pero aún no se han verificado. El complemento verifica la compatibilidad con ACP al inicio sin requerir una versión exacta de Cursor.

Configurar la autenticación con clave de API

Antes de usar el complemento, crea una clave de API en el panel de Cursor. Configura ~/.cursor/auth.json bajo el mismo usuario del sistema operativo que ejecuta Codex o Claude Code. El archivo debe contener solo el campo apiKey, sin otros campos:

{
  "apiKey": "YOUR_CURSOR_API_KEY"
}

Verifica la autenticación usando el almacén de credenciales respaldado por archivo:

AGENT_CLI_CREDENTIAL_STORE=file cursor-agent status --format json

Confirma que el comando de estado informe que estás autenticado antes de iniciar una tarea delegada. Ambas configuraciones del complemento establecen AGENT_CLI_CREDENTIAL_STORE=file, así que usa esa misma configuración para el estado. En macOS esto selecciona el almacenamiento de archivos en lugar de Keychain; un inicio de sesión anterior en Keychain no reemplaza esta configuración.

La guía oficial de autenticación de Cursor explica la autenticación y las comprobaciones de estado. La variable de entorno del almacén de archivos es una opción de la versión compatible de Cursor Agent utilizada por este complemento; no está documentada en esa página.

Instalación en Codex

Consulta la guía oficial de instalación de complementos de Codex. Para este repositorio, ejecuta estos comandos en tu terminal con la CLI de Codex disponible en PATH:

codex plugin marketplace add arikon/agents-cursor-subagent-plugin --ref main
codex plugin add agents-cursor-subagent-plugin@agents-cursor-subagent-plugin

El primer comando registra un repositorio de GitHub como marketplace; el segundo instala el complemento desde su instantánea del marketplace. Verifica los marketplaces configurados y los complementos instalados con:

codex plugin marketplace list --json
codex plugin list --json

Inicia una nueva tarea de Codex después de instalar el complemento para que Codex cargue sus habilidades y el servidor MCP. También puedes abrir /plugins dentro de la CLI de Codex para inspeccionar el marketplace configurado y el complemento instalado.

Actualizar el complemento de Codex

Actualiza la instantánea del marketplace y luego reinstala el complemento en caché:

codex plugin marketplace upgrade agents-cursor-subagent-plugin
codex plugin remove agents-cursor-subagent-plugin@agents-cursor-subagent-plugin
codex plugin add agents-cursor-subagent-plugin@agents-cursor-subagent-plugin

Inicia una nueva tarea de Codex solo después de que el plugin add final tenga éxito.

Actualización importante: cursor_wait

Esta versión elimina after_event_id y after_progress_revision de cursor_wait. Antes de actualizar, finaliza o cierra cada sesión delegada de Cursor y detén el proceso MCP. Luego ejecuta los comandos de actualización anteriores e inicia una nueva tarea de Codex para que cargue la habilidad y las herramientas instaladas coincidentes. Reemplazar archivos del complemento mientras una tarea anterior está abierta no actualiza el proceso MCP de esa tarea.

Para revertir, usa la revisión anterior del complemento, repite el mismo límite de cierre/reinicio y abre otra tarea nueva. No combines una habilidad anterior con el nuevo tiempo de ejecución, ni la nueva habilidad con el tiempo de ejecución anterior.

Instalación en Claude Code

Consulta la guía oficial de instalación de complementos de Claude Code y la referencia de comandos de la CLI. El mismo repositorio de GitHub es un marketplace de Claude Code. Requiere node y un Cursor Agent autenticado disponible como cursor-agent en PATH; establece CURSOR_AGENT_COMMAND en el entorno de Claude Code solo cuando el comando tenga una ubicación no estándar.

claude plugin marketplace add arikon/agents-cursor-subagent-plugin
claude plugin install agents-cursor-subagent-plugin@agents-cursor-subagent-plugin --scope user
claude plugin list --json

Ejecuta estos comandos en tu terminal. --scope user hace que el complemento esté disponible para ti en todos los proyectos; usa --scope project para compartir la declaración del complemento con un repositorio en su lugar. El complemento de Claude Code se llama agents-cursor-subagent-plugin, y su marketplace se llama agents-cursor-subagent-plugin.

Reinicia Claude Code después de la instalación para cargar el complemento. En una sesión existente, /reload-plugins también aplica cambios de complementos; usa /plugin para inspeccionar los complementos instalados.

Actualizar el complemento de Claude Code

Actualiza el marketplace y el complemento instalado después de una nueva revisión de Git, luego reinicia Claude Code para cargar el servidor MCP actualizado:

claude plugin marketplace update agents-cursor-subagent-plugin
claude plugin update agents-cursor-subagent-plugin@agents-cursor-subagent-plugin

Instalar el complemento solo hace que las herramientas MCP cursor_* existentes y la habilidad cursor-subagent estén disponibles. No aprueba acciones de Cursor: preguntas, planes y solicitudes de permisos fuera de alcance, destructivas, externas o relacionadas con credenciales aún requieren la misma autoridad explícita que en Codex.

Uso

Pide al asistente anfitrión que delegue una tarea acotada a Cursor, por ejemplo:

Pide a Cursor que revise src/parser.ts para verificar su corrección sin cambiar archivos.

La habilidad cursor-subagent incluida guía al asistente a través de la delegación, permisos, seguimientos y limpieza.

Modos

Modo	Úsalo para
ask	Investigación de solo lectura, preguntas, diagnóstico y revisión de código.
plan	Preparar un plan para aprobación.
agent	Implementación dentro de los cambios que autorizaste.

Herramientas MCP

Tarea	Herramientas
Delegar y seguir el progreso	cursor_delegate, cursor_wait
Responder a solicitudes pendientes	cursor_answer_question, cursor_answer_plan, cursor_answer_permission
Continuar el trabajo entre turnos	cursor_send_prompt, cursor_set_mode
Leer resultados más largos	cursor_read_result
Reanudar o cerrar una sesión	cursor_resume_session, cursor_close_session
Diagnóstico y recuperación avanzados	cursor_start_session, cursor_session_status, cursor_cancel

cursor_wait observa un turno abordado con session_id, turn_id y un timeout_ms opcional. Devuelve la solicitud pendiente actual de inmediato, un resultado terminal repetible mientras se conserva, o una instantánea de tiempo de espera con un extracto de progreso acotado. No requiere cursores de eventos o progreso.

Seguimientos y reanudación

Continúa un turno completado con cursor_send_prompt mientras su sesión esté activa. Un seguimiento proporcionado durante un turno activo espera a que ese turno termine; el complemento no puede dirigir un turno en ejecución. Cualquier resultado que no sea un turno completado requiere una nueva decisión del usuario antes de continuar.

Usa cursor_resume_session para intentar reabrir una conversación de Cursor conservada después de que su sesión local se haya cerrado o expirado.

Una reanudación exitosa no prueba que el contexto anterior se haya restaurado. Incluye el contexto y las restricciones necesarias para la siguiente tarea. Para una revisión, proporciona la línea base o la instantánea junto con los nuevos cambios; si esa evidencia falta, informa la revisión como no verificable.

Lectura de resultados completos

Los turnos completados incluyen una vista previa del resultado de 8 KB. El tiempo de ejecución conserva el resultado completo hasta 1 MiB; los resultados más grandes fallan con terminal_result_limit.

Cuando result.truncated:true, usa cursor_read_result desde el desplazamiento cero, siguiendo cada next_offset hasta eof. Lee el resultado completo antes de informarlo, enviar un seguimiento o cerrar la sesión.

Configuración del espacio de trabajo y la sesión

Prefiere el cwd de un árbol de trabajo verificado separado para tareas que puedan cambiar archivos o ejecutarse en paralelo. Una copia canónica está permitida cuando el usuario autorizó los cambios y acepta el riesgo de coordinación.

Para trabajo de solo lectura, selecciona ask y restringe las lecturas y búsquedas al alcance autorizado. Selecciona agent antes de realizar cambios autorizados. Cambia de modo con cursor_set_mode solo entre turnos.

Para cambiar model, effort, fast o plugin_dirs, cierra la sesión inactiva y reanúdala de inmediato con el ID de conversación de Cursor conservado y la nueva configuración. Estas configuraciones de inicio no se pueden cambiar en el lugar.

Usa un nombre de modelo base no vacío sin [ o ]. El valor opcional effort debe ser un token no vacío que coincida con [A-Za-z0-9._-]+.

Cierra la sesión cuando el flujo de trabajo delegado finalice, se abandone o falle de manera irrecuperable.

Permisos y alcance

El transporte local es Codex o Claude Code → complemento MCP → Cursor ACP (stdio JSON-RPC).

De forma predeterminada, el complemento inicia Cursor con sandboxing habilitado y Smart Auto (--auto-review), por lo que Cursor puede ejecutar automáticamente llamadas a herramientas que clasifique como seguras. Las preguntas, los planes y las solicitudes de aprobación permanecen pendientes hasta que se respondan.

La configuración del marketplace de Git suprime las indicaciones MCP del lado de Codex. El canario de lanzamiento portátil usa la ruta de elicitación predeterminada del adaptador. Estas configuraciones de transporte no amplían la autoridad otorgada por el usuario.

En el modo agent, Cursor puede crear o reemplazar archivos UTF-8 regulares en cualquier lugar dentro del cwd seleccionado. Las comprobaciones de alcance del complemento no son un sandbox del sistema operativo ni un motor de políticas exacto por acción.

Para tareas con capacidad de escritura y revisiones más limitadas que la copia de trabajo, el asistente anfitrión incluye AUTHORIZED_ACTIONS y NO_SCOPE_EXPANSION en la indicación delegada. Estas cláusulas comunican el límite de la tarea; no agregan aplicación en tiempo de ejecución. La habilidad incluida proporciona el formato exacto de la indicación.

El complemento no usa IPC basado en archivos y expone solo sus controles MCP documentados. Los adaptadores específicos de versión y los fixtures dorados definen los detalles subyacentes de la CLI y el protocolo.

Desarrollo

Consulta la guía de desarrollo para comandos de verificación, instalación portátil, aceptación de comportamiento y migración de adaptadores específicos de versión.