Disponibilidade de material de suporte

Este texto do catálogo contém as orientações inline abaixo, mas não inclui os seguintes caminhos de suporte. São pré-requisitos externos, não arquivos agrupados:

• <support-root>/references/socket-api.md

Obtenha o material necessário da fonte upstream declarada ou de uma instalação fornecida pelo usuário dessa fonte. Resolva cada caminho em relação a essa instalação, inspecione seu conteúdo e verifique quaisquer licenças e pré-requisitos de execução aplicáveis. Não execute um comando nem afirme que um procedimento referenciado foi seguido até que seu arquivo necessário exista. Não fabrique os scripts ausentes nem trate um arquivo não relacionado com o mesmo nome como equivalente. Etapas independentes totalmente documentadas aqui podem prosseguir dentro do escopo autorizado do usuário; relate qualquer etapa dependente como indisponível.

Controle cmux

Quando Usar

• Use quando precisar inspecionar, criar, fechar ou reorganizar painéis, superfícies ou áreas de trabalho do cmux.
• Use quando precisar enviar entrada ou monitorar agentes em execução dentro do cmux.

cmux é um aplicativo de terminal nativo do macOS para executar múltiplos agentes de codificação de IA em paralelo. Ele expõe uma CLI (cmux) e uma API JSON-RPC de socket Unix (/tmp/cmux.sock) para controle completo de topologia e navegador.

Conceitos Principais

• Janela — janela cmux de nível superior do macOS
• Área de Trabalho — aba lateral dentro de uma janela (um contexto de branch/projeto git)
• Painel — região dividida dentro de uma área de trabalho
• Superfície — aba dentro de um painel (terminal ou navegador)

Os identificadores (handles) padrão são referências curtas (workspace:2, pane:1, surface:7); UUIDs são aceitos como entrada. Adicione --id-format uuids|both para saída de UUID.

Sintaxe de referência — acerte isso ou falhe silenciosamente

• Sempre use referências PREFIXADAS (pane:38, surface:46). Um número puro é tratado como um ÍNDICE, não um ID — --surface 46 significa "a superfície no índice 46" (geralmente inexistente → falha silenciosa), NÃO surface:46.
• read-screen e capture-pane NÃO têm a flag --pane — eles visam apenas --workspace ou --surface. Passar --pane gera erro, e um alvo puro/ausente volta para sua PRÓPRIA superfície (você lerá seu próprio rodapé e tirará conclusões erradas). Para ler um painel: resolva-o para uma superfície PRIMEIRO com cmux list-pane-surfaces --pane pane:N, depois cmux read-screen --surface surface:N.
• Nunca anexe 2>/dev/null a comandos cmux. Erros vão para stderr com código de saída 1; suprimi-los te cega para seus próprios erros de referência/flag (a principal causa de "(sem saída)").

Detectar cmux em um Shell

[ -S "${CMUX_SOCKET_PATH:-/tmp/cmux.sock}" ] || exit 0   # bail if not in cmux
[ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "inside cmux surface"

Variáveis de ambiente injetadas em cada terminal iniciado pelo cmux: CMUX_WORKSPACE_ID, CMUX_SURFACE_ID, CMUX_SOCKET_PATH, CMUX_PORT. Sempre ancore a automação em CMUX_WORKSPACE_ID — a área de trabalho visualmente focada pode não ser a área de trabalho chamadora do agente.

Início Rápido — Topologia

cmux identify --json                              # who am I (window/workspace/pane/surface)
cmux tree                                         # full hierarchy
cmux list-workspaces --json
cmux list-panes --workspace "$CMUX_WORKSPACE_ID"
cmux list-surfaces --workspace "$CMUX_WORKSPACE_ID"

cmux new-workspace --name "feature-x" --cwd /path/to/repo
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type terminal --direction right --focus false
cmux new-pane --workspace "$CMUX_WORKSPACE_ID" --type browser  --direction right --url http://localhost:3000
cmux move-surface --surface surface:7 --pane pane:2 --focus false
cmux split-off --surface surface:7 right
cmux reorder-surface --surface surface:7 --before surface:3
cmux close-surface --surface surface:7

Sondando Agentes Pi em Painéis — Mantenha os Sleeps Curtos

Ao iniciar um Agente Pi dentro de um painel cmux e sondar por saída, use intervalos sleep curtos (2–5s). Pi é rápido e minimalista, e o usuário o executa no Opus 4.8 Fast via OpenRouter, que transmite tokens extremamente rápido. NÃO use sleep 15 a menos que seja genuinamente necessário (uma grande compilação/refatoração) — na maioria das vezes sleep 2–sleep 5 é mais do que suficiente.

Após cada verificação do agente, envie uma atualização de status de uma linha para o usuário: o que o agente está fazendo e se está no caminho certo. Mantenha-o extremamente conciso.

Nota do cmux do Claude Code: após o Claude terminar, ele pode pré-preencher uma mensagem prevista para o próximo usuário; esse rascunho é o Claude, não o usuário falando.

Enviar Entrada

…