Cursor Delegate

Quando Usar

• Você quer delegar uma tarefa de codificação delimitada para um cursor implementador separado (Cursor Agent) e depois revisar o diff dele.
• O usuário pediu explicitamente a delegação para este implementador.

Você é o orquestrador. Entregue uma tarefa de codificação delimitada para um implementador separado — o Cursor Agent CLI — depois revise o que ele produziu e implemente você mesmo. Você escreve o briefing e é responsável pelo julgamento; o Cursor digita em sua própria sessão; você verifica e commita.

O ciclo precisa apenas de um comando de shell e acesso a arquivos, então qualquer orquestrador comparável pode controlá-lo.

Quando NÃO Usar

• A tarefa é pequena o suficiente para ser feita inline; o overhead da delegação não vale a pena.
• O CLI cursor-agent não está instalado ou autenticado (execute cursor-agent login).
• Você quer escrever o código você mesmo, ou só precisa da opinião do Cursor sobre um código que você escreveu (um dispatch --read-only cobre isso — veja abaixo — mas uma revisão simples pode não precisar de delegação alguma).

Pré-requisitos (verificar uma vez)

1. cursor-agent --version funciona. Se não, siga o instalador para sua plataforma em cursor.com/cli, inspecione o que ele executará e autentique com cursor-agent login.
2. cursor-agent status mostra que você está logado.
3. Você está (ou apontará --cd para) o repositório git de destino. O relay passa --trust, então aponte apenas para repositórios nos quais você confia.

Escolha o Modelo

Omitir --model usa seu padrão do Cursor (geralmente auto — o Cursor escolhe). Para fixar um, passe --model <name> com um nome da saída cursor-agent models ativa da conta — selecione dessa lista em vez de inventar um nome. Formas parametrizadas como <name>[context=1m,effort=high] são encaminhadas como estão. O modelo que realmente serviu a execução é registrado como resolvedModel em result.json.

O Ciclo

Execute estes cinco passos por tarefa. Os passos 1, 4 e 5 exigem julgamento; 2 e 3 são mecânicos.

1. Escreva o Briefing

O Cursor vê apenas o texto que você envia mais o que ele pode inspecionar no workspace — sem histórico de chat ou contexto compartilhado. Inclua o objetivo, estado atual, o que mudar, o que deixar intocado, os portões reais do projeto e um contrato de relatório. Diga ao Cursor para não commitar. Mantenha uma tarefa por briefing. Veja references/writing-the-brief.md.

2. Dispatch

Use o helper incluso. Ele envolve cursor-agent -p, alimenta o briefing na entrada padrão, captura o stream de eventos estruturados e escreve result.json. (<skill-dir> é a pasta instalada contendo este SKILL.md.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (plan mode — review/diagnosis, no edits):  add --read-only
# write-capable without automatic command approval:   add --no-force
# explicitly override Cursor's sandbox for this run:  add --sandbox enabled|disabled
# pin a model from `cursor-agent models`:              add --model <name>
# resume the most recent session:                      add --resume-last  (delta brief only)
# resume a specific session:                           add --session <id> (delta brief only)
# hard time limit (watchdog):                          add --timeout 2h  (the 30m default suits short runs; implementation briefs routinely need 1-2h)
# see all options:                                     node .../relay.mjs --help

O cwd do processo filho fixa o workspace. No Cursor 2026.07.23 ou mais novo, use flags repetíveis --add-dir apenas para diretórios de workspace extras. O relay escreve artefatos sob o diretório temporário do sistema por padrão e nunca commita. Veja references/dispatch-and-poll.md.

3. Espere a Conclusão

O helper bloqueia até que o Cursor termine. Execute-o com a facilidade de comando em background do orquestrador, ou coloque-o em background no shell e faça polling para result.json. Um erro de uso pré-execução sai com 2 e não escreve resultado; um cursor-agent ausente sai com 127 e escreve status: "cursor_agent_unavailable".

Confie no estado do processo e na árvore de trabalho em vez de um display de progresso. Conclusão significa que o processo saiu e result.json existe. O relatório completo do Cursor é o campo finalMessage em result.json (também impresso por completo no stdout entre os marcadores de relatório).

Observação sobre Windows + hooks: se o usuário tiver hooks do Cursor configurados (~/.cursor/hooks.json, ou hooks do Claude Code PreToolUse, que o cursor-agent importa), o dispatch a partir de um Git Bash (MSYS)

…