Orchestrating terminal agents

Orquestrando agentes no terminal (kitty)

Três camadas

Camada	Script	Para quê
Primitivas	scripts/kittyctl.py	Dirigir qualquer programa numa aba: criar, digitar, mandar tecla, esperar, ler a tela.
Receita	scripts/fanout.py	O caso pronto: N worktrees + N agentes + prompt, numa chamada.
Coordenação	scripts/wavectl.py	Fechar o ciclo: barreira até todos terminarem, broadcast da wave seguinte nas mesmas abas, limpeza das worktrees.

# os scripts moram em scripts/ ao lado deste SKILL.md — instalado via symlink,
# o caminho canônico é o da skill:
K=~/.claude/skills/orchestrating-terminal-agents/scripts
python3 $K/kittyctl.py --help      # primitivas
python3 $K/fanout.py --help        # fan-out
python3 $K/wavectl.py --help       # barreira / broadcast / limpeza

As três regras invioláveis

Não são estilo — cada uma vem de um comportamento medido que falha em silêncio se ignorado.

1. Nunca confie no exit code de um send-*

kitty @ send-key e kitty @ send-text setam disallow_responses: saem com exit 0 mesmo casando zero janelas. Medido aqui — kitty @ send-key --match var:agent=NAOEXISTE enter → exit 0. Um script errado parece funcionar sem fazer nada.

O kittyctl pré-checa todo matcher com ls (que reporta no-match) e aborta com exit 2 em vez de mentir sucesso. A confirmação pós-envio fica com quem orquestra: leia a tela com capture/ wait-for depois de agir (é o que o fanout --via-keys faz antes de mandar Enter). Se você chamar kitty @ na mão, faça as duas coisas.

2. Texto e Enter em chamadas separadas

O Claude Code liga bracketed paste (DECSET 2004). Com o envelope de colagem ativo, um \r no fim do mesmo send-text cai dentro dos brackets em vez de submeter. E o tratamento de CR do Claude Code já mudou entre versões — nunca assuma que newline final submete.

python3 $K/kittyctl.py send-text --match var:agent=1 --text 'meu prompt'   # só digita
python3 $K/kittyctl.py send-key  --match var:agent=1 enter                 # só submete

send-text sempre manda o texto por stdin (literal). Testado com $HOME, crases, aspas e barras — chega verbatim. Use --paste só para prompt multi-linha.

3. Tecla especial vai por send-key, com nome simbólico

send-key shift+tab — nunca escape cru. O kitty escolhe a codificação conforme o modo que a TUI negociou (\x1b[Z legado, \x1b[9;2u sob o kitty keyboard protocol); um escape fixo quebra no segundo caso. send-raw existe só para sequências que não são tecla.

Gotchas que custaram tempo

• Shift+Tab CICLA, não liga plan mode. No Claude Code 2.1.218 a ordem é auto → manual → accept edits → plan — 3 teclas a partir do default, e a ordem muda entre versões. Nunca conte teclas: cicle até a tela dizer plan mode on (é o que fanout.py faz em cycle_to_plan). Melhor ainda: use a flag --permission-mode plan e não mande tecla nenhuma.
• Toda worktree nova dispara o diálogo de confiança do workspace. Sem tratar, a aba fica parada nele para sempre — inclusive no caminho por flags. fanout.py detecta e confirma (desligue com --no-trust).
• Um agente que roda dentro do Claude Code vaza CLAUDE_* e TMUX no ambiente. O filho acusa "Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION" e acha que vive num pane tmux alheio. O comando é embrulhado em /usr/bin/env -u … (lista em LEAKY_ENV).
• O socket some junto com a última janela. Fechar a última aba mata o processo do kitty e o socket. Quem orquestra não pode assumir que a instância de ontem existe — resolve_addr(start=True) sobe uma quando falta.
• --listen-on na linha de comando NÃO anexa o PID (fica @fan exato); só a diretiva listen_on do kitty.conf vira @mykitty-<pid>. Por isso a descoberta varre ss -xln por prefixo em vez de adivinhar o nome.
• Selecione por --var, nunca por título — o TUI reescreve o título da janela. Matcher booleano funciona: --match 'var:fan=<run> and var:agent=2'.
• --next-to não agrupa abas por remote control. O help avisa que ele é ignorado a menos que a janela casada esteja na aba alvo (a ativa) — medido: um fan-out de 3 abas se espalhou por 2 janelas. Para agrupar: crie a primeira sem --keep-focus (ela precisa virar a ativa), e antes de cada aba seguinte faça focus-window --match id:<âncora> e então --type=tab --keep-focus.
• launch roda o programa direto, sem shell. Encadear exige sh -c "… && exec claude". E --cwd precisa existir: o path vai direto ao spawn() em C, então diretório inexistente é falha dura, não fallback pra home. Crie a worktree antes do launch.

Flags antes de teclas

Se o programa tem flag para o que você quer, use a flag. Injeção de teclas é um recurso para quando não há alternativa — não é o caminho principal.

# determinístico: perfil + modelo + mode + effort + prompt, sem tecla nenhuma
claude --permission-mode plan --model opus --effort max "meu prompt"

Teclas ficam para: agentes sem flag equivalente (kimi, pi), intervir numa sessão já rodando (/compact, ESC para interromper, responder um prompt de permissão) e o modo --via-keys.

Escolhendo perfil, modelo, mode e effort

O fanout.py mapeia cada eixo para a flag do Claude Code correspondente (todas verificadas no binário 2.1.218):

Eixo	Flag	Valores	Default
Instalação	CLAUDE_CONFIG_DIR	--profile asd (~/.claude) · --profile dsa (~/.claude-secundaria) · os seus via FANOUT_PROFILES=nome=dir,… · --config-dir <dir> direto	asd
Modelo	--model	opus · fable · sonnet · haiku · opus[1m] · fable[1m] · nome completo (claude-fable-5)	o das settings do perfil
Mode	--permission-mode	--mode plan (ou o alias --permission-mode plan) · acceptEdits · auto · bypassPermissions · manual · dontAsk · none	plan
Effort	--effort	low · medium · high · xhigh · max · none	max
Permissões	--dangerously-skip-permissions	--yolo / --no-yolo	--yolo LIGADO

Perfis são só nomes para CLAUDE_CONFIG_DIRs — a instalação inteira (credenciais, MCP, histórico) é escolhida pelo dir, não por login. asd/dsa são os atalhos pessoais do autor; sinônimos main/ secondary também funcionam, e FANOUT_PROFILES/--config-dir cobrem qualquer outro layout.

Atenção ao default do yolo: todo launch de claude sai com --dangerously-skip-permissions a menos que você passe --no-yolo. Em plan mode isso significa: aprovado o plano, a execução roda sem gates de permissão. O binário do claude é resolvido por FANOUT_CLAUDE_BIN → PATH → ~/.local/bin/claude. Gotcha: um --model inválido não dá erro — o claude só imprime "There's an issue with the selected model" e fica no seletor (a aba trava). Confira o nome; em dúvida, omita e use o default das settings.

Onde as abas rodam (pwd)

• Com worktree (default): cada aba abre numa git worktree nova, criada antes do launch (--cwd inexistente é falha dura de spawn). Convenção <pai>/<repo>.worktrees/<branch>.
• Sem git — --no-worktree: as N abas abrem direto em --cwd <dir> (default: --repo). É o controle de pwd puro, para quando não se quer branch nenhum.

Um prompt para todos, ou um por agente

--prompt e --prompt-file são repetíveis:

• 1 prompt → compartilhado por todos os N agentes (N independentes atacando a mesma coisa).
• N prompts → um por agente na ordem (dividir trabalho: agente 1 = Alpha, agente 2 = Beta…). Nesse caso o próprio nº de prompts define quantos agentes subir, sem precisar de --count.
• Qualquer outra combinação (ex.: 2 prompts para 3 agentes) falha com mensagem clara em vez de adivinhar.

# 3 independentes, mesmo prompt
fanout.py --count 3 --repo ~/X --prompt "refatore o auth"
# 3 agentes, um prompt cada (count inferido)
fanout.py --repo ~/X --prompt "cuide do auth" --prompt "cuide do cache" --prompt "cuide dos logs"
# um arquivo por agente
fanout.py --repo ~/X --prompt-file a.md --prompt-file b.md

Prompts multi-linha e grandes

Resolvido sozinho, nos dois caminhos:

• Por flag (default): o prompt vai por argv. Newlines e tamanho não importam (limite prático = ARG_MAX, ~2 MB) e nada é reinterpretado. Passe com --prompt-file arquivo.md ou --prompt-file - (stdin) para prompts longos.
• --via-keys: multi-linha vai como bracketed paste (o \n fica literal dentro do envelope, não vira Enter); o Claude Code colapsa em [Pasted text #N +M lines] e envia o conteúdo inteiro no submit. O fanout.py verifica que o prompt chegou no composer (lendo a tela) antes de mandar Enter — testado com 62 linhas / ~4,8 KB contendo $, aspas e barras, chegando íntegro.

Waves: saber quando terminou e mandar a próxima

O wavectl.py fecha o ciclo do fan-out. O fanout injeta em cada claude um hook Stop (via --settings, válido só naquela sessão) que grava uma linha JSONL por fim de resposta em ~/.cache/fan/<run_id>/status/, e grava o manifest da run no mesmo dir — é o contrato que o wavectl lê.

wavectl.py await  --run <id> --notify       # barreira: bloqueia até todos terminarem
wavectl.py status --run <id>                # fotografia, sem bloquear
wavectl.py send   --run <id> --text 'commite tudo com mensagem descritiva'  # wave 2 (o modelo executa)
wavectl.py await  --run <id>                # barreira: todos commitaram
wavectl.py send   --run <id> --text '/exit' # /exit é do TUI — VOCÊ digita, não o modelo
wavectl.py await  --run <id> --expect exit  # barreira: as abas fecharam
wavectl.py finish --run <id>                # remove worktrees (repo principal, serializado)

Três regras, todas de comportamento medido ou documentado:

• A barreira é por nº de wave, não por relógio — o fanout marca a run na wave 1 e cada wavectl send incrementa o contador; o await --expect stop espera cada agente acumular ≥N stops. Assim tanto faz o agente terminar antes ou depois do await começar (baseline por relógio perde essa race — medido). Stop dispara por fim de resposta: um agente parado pedindo input também conta como terminado (é o que você quer — precisa de atenção). Runs com --no-hook caem no fallback heurístico (rodapé idle estável por 3 leituras), que dá falso positivo: em 2026-07-25 ele declarou "1/1 terminaram, stops 0, tela idle" um minuto após o launch, com os dois agentes em plena execução — ele pega a janela entre duas chamadas de ferramenta. Sinal muito melhor, se precisar de um: esc to interrupt só existe no rodapé enquanto o Claude Code trabalha; exija AUSÊNCIA em duas leituras seguidas. Mas o certo é não usar --no-hook (veja abaixo).
• O orquestrador "é avisado" rodando await como background task — a conclusão da task É a notificação. --notify manda notify-send para o humano.
• O agente NUNCA remove a própria worktree — o git recusa (cannot remove worktree … is the current working directory) e apagar o diretório por baixo dele deixa lock e metadata stale. A wave final é "commita" (linguagem natural, o modelo executa) seguida do broadcast literal /exit (slash command é do TUI — quem digita é você; mandar "rode /exit" vira um turn do modelo explicando que ele não pode — medido). O finish remove a partir do repo principal, sob o mesmo lock da criação, recusa worktree suja (sem --force) e lista os branches para o merge — um a um, nunca octopus, que aborta inteiro no primeiro conflito.

Detalhe: o --settings injetado SOMA aos hooks do projeto, não os substitui. Hooks próprios continuam valendo, e --no-hook NÃO é necessário para preservá-los. Medido em 2026-07-25 (Claude Code 2.1.220) com projeto de controle:

	PreToolUse do projeto	Stop do projeto	Stop injetado
sem --settings (controle)	bloqueou	rodou	—
com --settings só-Stop	bloqueou	rodou	rodou

A fusão é por evento e aditiva: os dois Stop rodaram na mesma sessão. Portanto use o hook (o default) mesmo em projeto com hooks próprios, inclusive de segurança. Escolher --no-hook "para não desligar os hooks do projeto" é trocar uma barreira determinística por um fallback de tela que dá falso positivo — sem ganho nenhum de segurança.

Receitas

Ver references/recipes.md — fan-out básico, um agente por item de uma lista, interromper todas as abas, /compact em todas, dirigir um TUI qualquer.

# 3 agentes, 3 worktrees, opus 1M em plan mode, prompt submetido
python3 $K/fanout.py --count 3 --repo ~/Projects/XPTO --model 'opus[1m]' --prompt "refatore o auth"

# 2ª conta, fable, aceitando edits, prompt longo por arquivo
python3 $K/fanout.py --count 2 --repo ~/Projects/XPTO --profile dsa --model fable \
        --mode acceptEdits --prompt-file tarefa.md

# sem worktree: 4 abas no mesmo diretório
python3 $K/fanout.py --count 4 --no-worktree --cwd ~/Projects/XPTO --prompt "..."

# ver o que faria, sem fazer  ·  fechar tudo de uma run
python3 $K/fanout.py --count 3 --repo ~/Projects/XPTO --prompt "..." --dry-run
python3 $K/kittyctl.py close --match var:fan=<run_id>

As worktrees seguem uma convenção estável (<pai>/<repo>.worktrees/<branch> + git config branch.<b>.origdir/.origbranch), então qualquer fluxo de finalização de worktree (commit/push/merge) consegue descobrir de onde ela saiu e para onde volta.

<evolution>

Ao concluir uma tarefa que usou esta skill:

1. Verificado de verdade (aba abriu, tecla chegou, tela confirmou)? Lembre que send-* mente sucesso — só persista o que você leu de volta com capture.
2. Append em LEARNINGS.md com data e fonte: ordem nova do ciclo de modos, diálogo novo na inicialização de um agente, env var nova vazando, quirk de versão do kitty.
3. Padrão estável → destile para o SKILL.md e incremente version.
4. Não commite sozinho — deixe como git diff.