Headless e CI · Makuco

Nem toda execução tem terminal. A CLI tem dois caminhos sem interface: o makuco run, que roda um turno de uma skill, e o --auto, que roda o laço inteiro até acabarem os passos.

`makuco run` — um turno

makuco run <skill> [alvo...]

Invoca uma das duas skills orquestradoras contra o agente e imprime o turno no stdout. Sem interface, sem laço: um turno, e sai.

Argumento	Valores
`<skill>`	`analisar` · `desenvolver`
`[alvo...]`	Texto livre, anexado ao prompt como alvo. Opcional.

Flag	O que faz
`--cwd <caminho>`	Raiz do projeto. Padrão: diretório atual.
`--provider <id>`	Provider do agente. Padrão: `claude-code`.
`--model <nome>`	Modelo. Aceita alias (`opus`, `sonnet`, `haiku`). Nunca é gravado no config.
`--auto-approve`	Aprova as permissões sem perguntar.

makuco run analisar
makuco run desenvolver pbi_003 --model sonnet --auto-approve

A skill e o projeto são validados antes de o agente subir — erro de digitação não paga o custo de abrir processo.

Permissões e perguntas sem interface

Situação	O que acontece
`--auto-approve`	Aprova sem perguntar.
stdin é TTY	Imprime o pedido e lê a resposta: o id da opção ou o número dela.
stdin não é TTY, sem `--auto-approve`	Recusa o pedido, com aviso dizendo que a saída é `--auto-approve`.
O agente faz uma pergunta estruturada	Imprime a pergunta e as opções, e pula — o agente decide sozinho.

Perguntar não é aprovar

--auto-approve cobre permissão, não pergunta. A pergunta é sempre pulada no caminho headless: ler a linha de um pipe para responder uma pergunta que ninguém viu seria inventar resposta em nome de quem não está lá.

`--auto` — o laço inteiro

makuco --auto

Roda cada passo candidato sem pedir confirmação, até os passos acabarem, e retorna. Não há chat, /workflow nem /skills — é o motor, não a interface.

Combine com --auto-approve para não parar em permissão:

makuco --auto --auto-approve

--yolo sem TTY degrada para cá

Passar --yolo num ambiente sem TTY não tem laço persistente para ligar, então ele vira o motor em --auto com aprovação automática — o que mantém a flag com significado em CI, em vez de virar um no-op silencioso. Com TTY, --yolo vence --auto e mantém o teclado vivo.

Um passo que termina sem avançar o estado é tentado de novo algumas vezes e depois estacionado, com aviso — sem isso o laço nunca terminaria.

Códigos de saída

Valem para makuco e makuco run:

Código	Significado
`0`	Sucesso — o turno terminou, ou o laço acabou os passos.
`1`	Erro.
`2`	Uso inválido — skill desconhecida, ou diretório sem `.claude/`.
`3`	O turno não entregou: recusa do agente, teto de tokens ou de requisições, ou passo estacionado.
`130`	Cancelado (`SIGINT`), na convenção do shell.

Os comandos de instalação usam outro contrato

No makuco update, no makuco unit sync e no skill/agent/prompt add, o 2 significa sucesso com pendência, não uso inválido. A tabela deles está em Comandos → Códigos de saída.

Você nunca vai ver 75

75 é protocolo interno entre o executável e o bundle, usado quando a CLI se atualiza e precisa reabrir. O executável consome esse código e nunca o propaga.

Sem TTY, sem interface

O comando makuco sem flag nenhuma também detecta a ausência de TTY e cai num modo de texto, linha a linha, em vez de tentar montar a interface. É o que torna possível ler o log de um turno num pipe.

O aviso de versão nova não aparece sem TTY: um modal esperando tecla numa esteira penduraria a execução inteira.