Codex Cursor Subagent Plugin

Plugin Codex e Claude Code Cursor Subagent

Use o Cursor Agent como um subagente interativo a partir do Codex ou do Claude Code. Delegue investigação de código, revisões, planejamento e implementação sem mover manualmente prompts e resultados entre aplicativos.

O plugin inicia o Cursor Agent instalado por meio do ACP e expõe sua sessão interativa por meio do MCP. Você pode acompanhar o progresso, responder perguntas, revisar planos e continuar com tarefas de acompanhamento.

Conteúdo

• Demonstração
• Requisitos
• Configuração do Cursor Agent
• Instalação no Codex
• Instalação no Claude Code
• Uso
• Permissões e escopo
• Desenvolvimento

Demonstração

Delegando uma tarefa ao Cursor a partir do Codex e, em seguida, retomando a sessão ACP para uma solicitação de acompanhamento:

Requisitos

• runtime e instalação portátil: Node.js 18+;
• Cursor Agent (cursor-agent) instalado e autenticado antes de usar o plugin (veja Configuração do Cursor Agent abaixo);
• Codex com suporte local a plugin/MCP, ou Claude Code com suporte a plugin.

Configuração do Cursor Agent

Instalar a CLI

O plugin não instala o Cursor Agent nem faz login por você. Instale e autentique-o sob o mesmo usuário do SO e no ambiente onde o Codex ou o Claude Code é executado. Siga o guia oficial de instalação da CLI do Cursor. No macOS, Linux ou WSL:

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

Mantenha ~/.local/bin no PATH do aplicativo host, ou defina CURSOR_AGENT_COMMAND para o caminho absoluto do executável do Agent. O instalador fornece a CLI atual. O plugin foi testado com o Cursor Agent 2026.08.25-3e8eec8. Espera-se que versões mais recentes funcionem se preservarem a interface ACP necessária, mas ainda não foram verificadas. O plugin verifica a compatibilidade com ACP na inicialização sem exigir uma versão exata do Cursor.

Configurar autenticação por chave de API

Antes de usar o plugin, crie uma chave de API no dashboard do Cursor. Configure ~/.cursor/auth.json sob o mesmo usuário do SO que executa o Codex ou o Claude Code. O arquivo deve conter apenas o campo apiKey, sem outros campos:

{
  "apiKey": "YOUR_CURSOR_API_KEY"
}

Verifique a autenticação usando o armazenamento de credenciais baseado em arquivo:

AGENT_CLI_CREDENTIAL_STORE=file cursor-agent status --format json

Confirme que o comando de status informa que você está autenticado antes de iniciar uma tarefa delegada. Ambas as configurações do plugin definem AGENT_CLI_CREDENTIAL_STORE=file, portanto, use essa mesma configuração para o status. No macOS, isso seleciona o armazenamento em arquivo em vez do Keychain; um login anterior no Keychain não substitui esta configuração.

O guia oficial de autenticação do Cursor explica autenticação e verificações de status. A variável de ambiente do armazenamento de arquivos é uma opção da versão suportada do Cursor Agent usada por este plugin; ela não está documentada nessa página.

Instalação no Codex

Veja o guia oficial de instalação de plugins do Codex. Para este repositório, execute estes comandos no seu terminal com a CLI do Codex disponível em PATH:

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

O primeiro comando registra um repositório GitHub como marketplace; o segundo instala o plugin a partir do snapshot do marketplace. Verifique os marketplaces configurados e os plugins instalados com:

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

Inicie uma nova tarefa do Codex após instalar o plugin para que o Codex carregue suas skills e o servidor MCP. Você também pode abrir /plugins dentro da CLI do Codex para inspecionar o marketplace configurado e o plugin instalado.

Atualizar o plugin do Codex

Atualize o snapshot do marketplace e reinstale o plugin em cache:

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

Inicie uma nova tarefa do Codex somente após o plugin add final ser bem-sucedido.

Atualização de quebra: cursor_wait

Esta versão remove after_event_id e after_progress_revision de cursor_wait. Antes de atualizar, finalize ou feche cada sessão delegada do Cursor e pare o processo MCP. Em seguida, execute os comandos de atualização acima e inicie uma nova tarefa do Codex para que ela carregue a skill e as ferramentas instaladas correspondentes. Substituir arquivos do plugin enquanto uma tarefa antiga está aberta não atualiza o processo MCP dessa tarefa.

Para reverter, use a revisão anterior do plugin, repita o mesmo limite de fechamento/reinício e abra outra nova tarefa. Não combine uma skill antiga com o novo runtime, nem a nova skill com o runtime antigo.

Instalação no Claude Code

Veja o guia oficial de instalação de plugins do Claude Code e a referência de comandos da CLI. O mesmo repositório GitHub é um marketplace do Claude Code. Ele requer node e um Cursor Agent autenticado disponível como cursor-agent em PATH; defina CURSOR_AGENT_COMMAND no ambiente do Claude Code somente quando o comando tiver um local não padrão.

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

Execute estes comandos no seu terminal. --scope user torna o plugin disponível para você em todos os projetos; use --scope project para compartilhar a declaração do plugin com um repositório. O plugin do Claude Code é nomeado agents-cursor-subagent-plugin, e seu marketplace é nomeado agents-cursor-subagent-plugin.

Reinicie o Claude Code após a instalação para carregar o plugin. Em uma sessão existente, /reload-plugins também aplica alterações de plugin; use /plugin para inspecionar os plugins instalados.

Atualizar o plugin do Claude Code

Atualize o marketplace e o plugin instalado após uma nova revisão do Git e, em seguida, reinicie o Claude Code para carregar o servidor MCP atualizado:

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

Instalar o plugin apenas disponibiliza as ferramentas MCP cursor_* existentes e a skill cursor-subagent. Isso não aprova ações do Cursor: perguntas, planos e solicitações de permissão fora do escopo, destrutivas, externas ou relacionadas a credenciais ainda exigem a mesma autoridade explícita que no Codex.

Uso

Peça ao assistente host para delegar uma tarefa limitada ao Cursor, por exemplo:

Peça ao Cursor para revisar src/parser.ts quanto à correção sem alterar arquivos.

A skill cursor-subagent incluída orienta o assistente na delegação, permissões, acompanhamentos e limpeza.

Modos

Modo	Use para
ask	Investigação somente leitura, perguntas, diagnóstico e revisão de código.
plan	Preparação de um plano para aprovação.
agent	Implementação dentro das alterações que você autorizou.

Ferramentas MCP

Tarefa	Ferramentas
Delegar e acompanhar o progresso	cursor_delegate, cursor_wait
Responder a solicitações pendentes	cursor_answer_question, cursor_answer_plan, cursor_answer_permission
Continuar o trabalho entre turnos	cursor_send_prompt, cursor_set_mode
Ler resultados mais longos	cursor_read_result
Retomar ou fechar uma sessão	cursor_resume_session, cursor_close_session
Diagnóstico e recuperação avançados	cursor_start_session, cursor_session_status, cursor_cancel

cursor_wait observa um turno endereçado com session_id, turn_id e um timeout_ms opcional. Ele retorna imediatamente a solicitação pendente atual, um resultado terminal repetível enquanto retido, ou um snapshot de timeout com um trecho de progresso limitado. Ele não requer cursores de evento ou progresso.

Acompanhamentos e retomada

Continue um turno concluído com cursor_send_prompt enquanto a sessão estiver ativa. Um acompanhamento fornecido durante um turno ativo aguarda o término desse turno; o plugin não pode direcionar um turno em execução. Qualquer resultado diferente de um turno concluído exige uma nova decisão do usuário antes de continuar.

Use cursor_resume_session para tentar reabrir uma conversa retida do Cursor após o encerramento ou expiração da sessão local.

Uma retomada bem-sucedida não prova que o contexto anterior foi restaurado. Inclua o contexto e as restrições necessários para a próxima tarefa. Para uma revisão, forneça a linha de base ou o snapshot junto com as novas alterações; se essa evidência estiver ausente, relate a revisão como não verificável.

Leitura de resultados completos

Turnos concluídos incluem uma prévia de resultado de 8 KB. O runtime retém o resultado completo em até 1 MiB; resultados maiores falham com terminal_result_limit.

Quando result.truncated:true, use cursor_read_result a partir do deslocamento zero, seguindo cada next_offset até eof. Leia o resultado completo antes de relatá-lo, enviar um acompanhamento ou fechar a sessão.

Configurações de workspace e sessão

Prefira o cwd de um worktree separado e verificado para tarefas que possam alterar arquivos ou ser executadas em paralelo. Um checkout canônico é permitido quando o usuário autorizou as alterações e aceita o risco de coordenação.

Para trabalho somente leitura, selecione ask e restrinja leituras e buscas ao escopo autorizado. Selecione agent antes de fazer alterações autorizadas. Alterne modos com cursor_set_mode somente entre turnos.

Para alterar model, effort, fast ou plugin_dirs, feche a sessão ociosa e retome-a imediatamente com o ID de conversa retido do Cursor e as novas configurações. Essas configurações de inicialização não podem ser alteradas no local.

Use um nome de modelo base não vazio sem [ ou ]. O valor opcional effort deve ser um token não vazio correspondente a [A-Za-z0-9._-]+.

Feche a sessão quando o fluxo de trabalho delegado terminar, for abandonado ou falhar irrecuperavelmente.

Permissões e escopo

O transporte local é Codex ou Claude Code → plugin MCP → Cursor ACP (stdio JSON-RPC).

Por padrão, o plugin inicia o Cursor com sandbox habilitado e Smart Auto (--auto-review), para que o Cursor possa executar automaticamente chamadas de ferramenta que classifica como seguras. Perguntas, planos e solicitações de aprovação permanecem pendentes até serem respondidos.

A configuração do marketplace Git suprime prompts MCP do lado do Codex. O canário de lançamento portátil usa o caminho de elicitação padrão do adaptador. Essas configurações de transporte não expandem a autoridade concedida pelo usuário.

No modo agent, o Cursor pode criar ou substituir arquivos UTF-8 regulares em qualquer lugar dentro do cwd selecionado. As verificações de escopo do plugin não são um sandbox do SO nem um mecanismo exato de política por ação.

Para tarefas com capacidade de escrita e revisões mais restritas que o checkout, o assistente host inclui AUTHORIZED_ACTIONS e NO_SCOPE_EXPANSION no prompt delegado. Essas cláusulas comunicam o limite da tarefa; elas não adicionam aplicação em runtime. A skill incluída fornece o formato exato do prompt.

O plugin não usa IPC baseado em arquivo e expõe apenas seus controles MCP documentados. Adaptadores específicos de versão e fixtures douradas definem os detalhes subjacentes da CLI e do protocolo.

Desenvolvimento

Veja o guia de desenvolvimento para comandos de verificação, instalação portátil, aceitação de comportamento e migração de adaptador específico de versão.