O que eu preciso antes de começar?

Windows 10/11 com PowerShell 5.1 (já vem no sistema) — sem WSL, sem tmux.
Claude Code instalado e logado.
Instalador do claude-bus — distribuído no grupo Vibe Coders. Rodou o instalador, o comando bus fica disponível em qualquer terminal.

Como ligar o monitor?

O monitor é o carteiro: processo leve em segundo plano que entrega as mensagens entre sessões. Sem ele, nada circula.

bus start     # liga o monitor (janela oculta, sobrevive ao fechamento do terminal)
bus status    # RODANDO ou PARADO + fila de cada agente
bus stop      # desliga o monitor

Pode fechar o terminal depois do bus start — o monitor continua rodando. Ele só morre com bus stop, logout ou reinicialização. Rodar bus start de novo é seguro: detecta se já está vivo e não duplica.

Como abrir um agente conectado ao bus?

bus open abre um terminal novo com uma sessão Claude que se registra no bus e arma a escuta sozinha:

bus open --name dev1 --cwd C:\projetos\meu-app --clean --danger

Flag	O que faz
`--name`	Apelido do agente na rede (obrigatório). É o nome que os outros usam no `--to`.
`--cwd`	Pasta onde a sessão nasce. Sem ela, usa a pasta atual.
`--role`	Persona no system prompt: `orquestrador`, `dev`, `code-review` (ou papéis seus em `~\.claude-bus\roles\`).
`--env`	Injeta variáveis de `~\.claude-bus\profiles\<perfil>.env` só naquela janela (ex.: provider alternativo).
`--clean`	Janela nasce com Claude original — limpa overrides de provider herdados do shell.
`--model`	Passa o modelo pro Claude (ex.: `--model opus`).
`--danger`	Roda sem prompts de permissão. Só em máquina sua.

Cuidado com pastas que têm CLAUDE.md restritivo (agentes de produção com guardrails): a persona do projeto prevalece e pode recusar o bus. Pra esses casos, abra o agente numa pasta neutra e referencie os arquivos do projeto nas mensagens.

Registrar uma sessão já aberta (manual)

bus register --name gestor --reader   # dentro de sessão Claude Code existente

Como enviar tarefas e perguntas?

bus send --to dev1 --type task "Crie o endpoint /api/leads em C:\projetos\meu-app. Criterio de aceite: testes passando. Reporte pelo bus."
bus send --to gestor --type query "Quantas issues abertas temos no Linear?"
bus send --to all --type notify "Deploy concluido as 18h."
bus send --to worker-novo --cwd C:\projetos\outro-app --type task "..."   # cria worker headless na pasta

Tipo	Quando usar
`task`	Tarefa pra executar. Gera resposta na thread.
`query`	Pergunta. Gera resposta na thread.
`notify`	Aviso. Não gera resposta (não responda notify!).
`reply`	Resposta dentro de uma thread (automático quando usa `--thread`).

Regra de ouro: o corpo deve ser autocontido — o destinatário não vê seu contexto. Inclua caminhos absolutos, critérios de aceite e o que reportar de volta. E peça sempre "responda pelo bus".

Como o agente recebe e responde?

Sessões abertas via bus open já escutam sozinhas: cada mensagem nova chega como evento [BUS] na conversa. O fluxo do agente é:

Executar a tarefa / responder a pergunta.
Responder sempre na thread indicada (exceto notify):

bus send --to <remetente> --thread <thread-id> "resultado: o que fez, arquivos tocados, pendencias"

Sem loop de cortesia: nada de responder "obrigado" — só conteúdo de trabalho, 1x, e para.

Como inspecionar a rede?

bus agents        # quem esta registrado (nome, status, pasta)
bus status        # monitor + mensagens pendentes por agente
bus inbox         # minhas mensagens pendentes (so lista, NAO consome)
bus read m-123    # corpo completo de uma mensagem
bus done m-123    # marca como processada (obrigatorio apos responder manualmente)

bus inbox só lista. Se você processou uma mensagem manualmente, rode bus done <id> — senão ela chega de novo como evento (execução duplicada).

Como montar um time completo?

Exemplo clássico — orquestrador + dev + reviewer, cada um na sua janela:

bus start
bus open --name orq  --role orquestrador --cwd C:\projetos --clean
bus open --name dev1 --role dev          --cwd C:\projetos\meu-app --clean --danger
bus open --name rev  --role code-review  --cwd C:\projetos\meu-app --clean

# dispara a missao pro orquestrador:
bus send --to orq --type task "Coordene dev1 e rev para implementar X. Delegue ao dev1, exija review do rev, reporte o resultado pelo bus."

O orquestrador delega, o dev executa, o reviewer aprova — e você só assiste. O próprio orquestrador pode convocar membros novos com bus open.

Deu problema — e agora?

Sintoma	Solução
Mensagem não chega	`bus status` → monitor PARADO? Roda `bus start`.
Thread travou / parou de responder	Limite de rodadas atingido (anti-loop, padrão 10). Libere com `bus unblock <thread-id>`. O id aparece no `bus status`.
Mensagem processada chegou de novo	Faltou `bus done <id>` após processar manualmente.
Agente recusou entrar no bus	Pasta tem CLAUDE.md com guardrails próprios. Abra o agente em pasta neutra.
Remetente aparecendo como `user`	Sessão antiga (pré v1.0.1) ou aberta sem `bus open`. Feche e reabra a janela com `bus open`.
Conversa longa demais foi cortada	Aumente `round_limit` em `~\.claude-bus\config.json` (padrão 10).