Como rodar o claude-bus.

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.

Qual o jeito mais rápido de montar um time? v1.3

Um assistente pergunta o essencial, abre o time e salva — da segunda vez em diante é um comando só. É o caminho recomendado: você não precisa decorar parâmetro nenhum.

bus setup

  claude-bus - montar um time

  Nome do time (vira o nome da sala): Time RCS
    -> usando: time-rcs
  Pasta do projeto: C:\projetos\rcs

  Modelo do time:
    [1] Solo         - so um dev
    [2] Dupla        - orquestrador + dev            (padrao)
    [3] Completo     - orquestrador + dev + revisor
    [4] Personalizado
  Escolha: 3

    motores: claude, grok, pi, kimi-code
    outro modelo no claude: claude --env <perfil>  (perfis: kimi)
  agentes do time: orq (orquestrador), dev (dev), rev (code-review)
  Algum agente em outro motor? (ex: dev=grok, revisor=pi, todos=pi; enter=todos Claude): dev=grok, revisor=pi
    dev: grok
    revisor -> rev: pi

  Quem trabalha sozinho, sem parar para pedir aprovacao?
    [1] So o dev                (padrao)
    [2] Todos os agentes
    [3] Ninguem - todos pedem aprovacao
  Escolha: 2

  Como abrir os agentes no herdr?
    [1] Abas no mesmo espaco      (padrao)
    [2] Lado a lado (tela dividida)
    [3] Um espaco separado para cada
  Escolha: 2

  Confira o time antes de abrir:
    sala:  time-rcs
    pasta: C:\projetos\rcs
    onde:  lado a lado
    - orq          orquestrador   claude  autonomo
    - dev          dev            grok    autonomo
    - rev          code-review    pi      autonomo

  Esta certo? (s/n) s

  Salvar como time 'time-rcs' para reabrir depois? (s/n) s

subindo time 'time-rcs' na sala 'time-rcs'
  monitor ........... ok
  orq                aberto (orquestrador, claude, autonomo)
  dev                aberto (dev, grok, autonomo)
  rev                aberto (code-review, pi, autonomo)

time no ar. fechar depois: bus down time-rcs

Como apontar o agente na pergunta de motor v1.5.2

O assistente imprime o roster do time antes de perguntar e aceita qualquer forma de citar o agente — nome curto, papel, papel escrito por extenso ou prefixo:

Cada acerto é confirmado na tela (revisor -> rev: pi). Nome que não bate com ninguém avisa e segue — nao achei agente 'qa' - o time tem: orq (orquestrador), dev (dev), rev (code-review) — em vez de sumir calado; apelido que serve para dois agentes pede o nome exato. O modelo Personalizado e o bus add também aceitam o papel por extenso: digitar revisor grava code-review, que é o papel que existe de verdade.

Depois do primeiro setup

bus up time-rcs      # reabre a sala e os agentes que faltam
bus down time-rcs    # fecha a sala e as abas do time
bus teams            # lista os times salvos

bus up é seguro de repetir: quem já está no ar é pulado, então rodar duas vezes não duplica agente.

Time de um agente só, ou do seu jeito

• Solo — abre só um dev. Para quando você não quer time, só um agente autônomo no projeto.
• Personalizado — você define agente por agente: nome, papel, motor e se trabalha sozinho, repetindo até dizer que chega. Serve para papéis fora do padrão (qa, arquiteto, redator).

Escolher outro modelo no assistente

Onde o assistente pede o motor, ele aceita mais que claude e grok — e lista antes os perfis que você já tem salvos:

    motores: claude, grok
    outro modelo no claude: claude --env <perfil>  (perfis: kimi, deepseek)
    Motor: claude --env kimi

Três formas equivalentes: claude --env kimi, claude:kimi, ou só kimi. Nos modelos prontos vale por agente, na mesma linha dos motores: dev=claude --env kimi.

Perfil que não existe é recusado na hora, com a lista dos que existem e onde criar — em vez de abrir o agente calado no modelo errado. Como criar um perfil: seção Outros modelos de IA.

Mexer no time depois de criado

bus add time-rcs                     # acrescenta UM agente (4 perguntas) e ja abre
bus remove qa --from time-rcs        # tira do time (some do arquivo tambem)

O bus add funciona com o time já rodando: o agente novo abre junto dos outros, sem interromper ninguém, e passa a subir junto nas próximas vezes.

Ele pergunta também onde abrir esse agente — aba no mesmo espaço, lado a lado, ou espaço separado. O padrão já vem do que o time usa, então enter basta para ele entrar junto.

Parar o time

bus down time-rcs     # para a sala e fecha as abas do time
bus stop time-rcs     # para a sala (aceita nome do time ou da sala)

Informar um nome que não existe dá erro e lista as opções, em vez de parar o time errado.

Autonomia — quem trabalha sem pedir aprovação

O assistente pergunta uma vez e vale para o time inteiro:

No modo personalizado a pergunta é por agente, então dá para misturar. A escolha fica salva: nas próximas aberturas o time volta igual.

Onde o time abre

Se você usa o herdr, o assistente pergunta como quer os agentes: abas no mesmo espaço (padrão), lado a lado com a tela dividida, ou um espaço separado para cada. A escolha fica no time — reabrir traz o mesmo arranjo.

O que o assistente assume por você

Todos herdam a pasta do projeto e o Claude como motor, salvo indicação contrária.

O arquivo do time

Fica salvo no seu computador e pode ser editado à mão, se quiser ajuste fino:

{
  "team": "time-rcs",
  "room": "time-rcs",
  "cwd": "C:\\projetos\\rcs",
  "agents": [
    { "name": "orq", "role": "orquestrador", "engine": "claude", "clean": true },
    { "name": "dev", "role": "dev", "engine": "grok", "danger": true },
    { "name": "rev", "role": "code-review", "engine": "claude", "clean": true }
  ]
}

Cada agente aceita ainda cwd (pasta própria), model e env (perfil de provider).

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

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

Registrar uma sessão já aberta (manual)

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

Quais presets de agente existem e como chamo cada um?

Preset é a personalidade que o agente assume ao nascer — vem no --role e vale do primeiro ao último turno da sessão. Três vêm prontos:

Anatomia do comando

bus open --name <apelido> --role <preset> --cwd <pasta> [--agent grok] [--env <perfil>] [--clean] [--model <m>] [--danger]

Combinando preset com motor

Preset e motor são independentes: qualquer preset roda em qualquer motor.

# time misto: orquestrador no Claude, dev no Grok, revisor no Claude
bus open --name orq --role orquestrador --cwd C:\projeto --clean
bus open --name dev-grok --role dev --agent grok --cwd C:\projeto --danger
bus open --name rev --role code-review --cwd C:\projeto --clean

# dois devs, motores diferentes, mesmo preset
bus open --name dev1 --role dev --agent grok --cwd C:\projeto --danger
bus open --name dev2 --role dev --env kimi --cwd C:\projeto --danger

Criar seu próprio preset

Um preset é um arquivo markdown com a personalidade escrita em português comum: quem o agente é, como trabalha, o que ele nunca faz. Salve como <nome>.md na pasta de presets e chame com --role <nome>.

# exemplo: presets/qa.md
# PAPEL: QA

Voce e o QA do time. Sua funcao e VALIDAR, nunca implementar.

Ao receber uma tarefa:
1. Rode os testes e o app de verdade.
2. Relate: o que passou, o que falhou, como reproduzir a falha.
3. Nunca edite codigo - reprovado volta para o dev.

Como rodar agentes com outros modelos de IA?

Cada agente pode subir num provider diferente — orquestrador no Claude original, dev num modelo mais barato (Kimi, DeepSeek, etc.). O truque são os perfis: um arquivo por provider em ~\.claude-bus\profiles\, cujas variáveis entram só na janela daquele agente.

1. Crie o arquivo de perfil

Um arquivo <nome>.env (formato CHAVE=VALOR, uma por linha, # comenta). Exemplo ~\.claude-bus\profiles\kimi.env:

ANTHROPIC_BASE_URL=https://api.kimi.com/coding/
ANTHROPIC_API_KEY=sua-key-aqui
ANTHROPIC_MODEL=k3
ANTHROPIC_DEFAULT_SONNET_MODEL=kimi-for-coding
ANTHROPIC_DEFAULT_HAIKU_MODEL=kimi-for-coding
CLAUDE_CODE_SUBAGENT_MODEL=kimi-for-coding

Para outro provider (ex.: DeepSeek), crie deepseek.env no mesmo formato com a URL, a chave e os modelos dele.

O perfil é procurado sempre em ~\.claude-bus\profiles\, mesmo dentro de uma sala: a chave é sua, não do time — um kimi.env serve todos. O mesmo vale para as personas de ~\.claude-bus\roles\.

2. Abra o agente apontando pro perfil

bus open --name dev-kimi --role dev --env kimi --cwd C:\projetos\meu-app --danger

Time com modelos misturados

bus open --name orq  --role orquestrador --cwd C:\projetos --clean            # Claude original
bus open --name dev1 --role dev          --cwd C:\projetos\app --env kimi --danger  # Kimi
bus open --name rev  --role code-review  --cwd C:\projetos\app --clean         # Claude original

Como rodar um agente Grok no time? v1.2

O bus não é preso ao Claude Code: ele precisa apenas de um agente de terminal que saiba retomar a própria conversa. O Grok sabe — então entra no time como qualquer outro membro.

bus open --name dev-claude --role dev --cwd C:\projeto --danger
bus open --name dev-grok --agent grok --role dev --cwd C:\projeto --danger   # mesmo time, motor diferente

Para registrar uma sessão Grok que você já abriu na mão:

bus register --name gk --agent grok --session <uuid-da-sessao>

As diferenças entre os dois CLIs são traduzidas automaticamente — você não precisa saber nenhuma delas:

O motor fica gravado no registro e aparece em bus agents, na coluna MOTOR. Um mesmo time pode ter Claude, Claude com outro provider (Kimi, DeepSeek) e Grok ao mesmo tempo.

Receitas prontas com Grok

# dev Grok autonomo, com o preset dev
bus open --name dev-grok --agent grok --role dev --cwd C:\projeto --danger

# revisor Grok (so le, nunca edita)
bus open --name rev-grok --agent grok --role code-review --cwd C:\projeto

# Grok num modelo especifico
bus open --name dev-grok --agent grok --role dev --model grok-code --cwd C:\projeto --danger

# conferir como vai abrir, sem abrir
bus open --name dev-grok --agent grok --role dev --cwd C:\projeto --danger --dryrun

Delegando para o agente Grok

Do ponto de vista de quem envia, não há diferença nenhuma — é o mesmo comando de sempre:

bus send --to dev-grok --type task "Implemente X em C:\projeto. Criterio de aceite: testes passando. Reporte pelo bus."

E o orquestrador pode convocar um Grok sozinho, se a tarefa pedir — basta ele abrir o agente com --agent grok.

Como rodar um agente pi no time? v1.4 · v1.5

O pi é o terceiro motor. Ele entra como dev ou revisor, recebe tarefa do gestor, executa no projeto e responde na mesma conversa — igual aos outros. A diferença está em como você acompanha o trabalho dele, e isso você escolhe.

Pelo assistente (recomendado)

Onde o assistente pergunta o motor de cada agente, responda dev=pi. Como o time tem um agente pi, ele faz uma pergunta a mais:

bus setup
  # ...
  agentes do time: orq (orquestrador), dev (dev)
  Algum agente em outro motor? (ex: dev=grok, revisor=pi, todos=pi; enter=todos Claude): dev=pi
    dev: pi

  Como abrir o agente pi (ele nao tem a ferramenta Monitor)?
    [1] Aba espelho - mostra cada entrega e a saida ao vivo   (padrao)
    [2] TUI de verdade - as mensagens chegam na conversa dele
  Escolha: 2

A escolha fica salva no time: bus up <time> reabre o pi do jeito que você decidiu. O resumo do time mostra qual dos dois está valendo:

  dev                aberto (dev, pi, autonomo, tui)
  dev                aberto (dev, pi, autonomo, espelho)

Na mão

# aba espelho: o pi trabalha sob demanda e a aba mostra cada entrega
bus open --name dev --agent pi --role dev --cwd C:\projeto

# TUI: a conversa do pi abre na tela e recebe as mensagens do time ao vivo
bus open --name dev --agent pi --tui --role dev --cwd C:\projeto

# conferir como vai abrir, sem abrir
bus open --name dev --agent pi --tui --role dev --cwd C:\projeto --dryrun

Não existe registro manual como no Grok: o bus cuida da identidade da conversa do pi sozinho. E --danger é aceito e ignorado, porque o pi já executa as ferramentas dele sem pedir aprovação.

Os dois modos, lado a lado

Ver o que qualquer agente fez

Toda entrega fica registrada por agente — a mensagem que chegou, a saída do motor e o resultado. Vale para Claude, Grok, pi e Kimi Code:

bus tail --name dev             # acompanha ao vivo (Ctrl+C sai)
bus tail --name dev --once      # imprime as ultimas linhas e sai
bus tail --name dev --lines 60  # quanto historico mostrar (padrao 30)

=== 03:21:16 [BUS] task de orq (thread t-...-bymm) ===
Responda pelo bus dizendo o conteudo de hello-pi.txt.
--- saida do motor (pi) ---
Vejo a palavra OK em hello-pi.txt.
=== 03:21:37 DELIVER-OK (21s) ===

É isso que a aba espelho mostra. O arquivo se limpa sozinho quando cresce demais.

Delegando para o agente pi

Nenhuma diferença de quem envia:

bus send --to dev --type task "Implemente X em C:\projeto. Criterio de aceite: testes passando. Reporte pelo bus."

Modelo e ferramentas

O provider e o modelo vêm da configuração do próprio pi (~\.pi\agent\settings.json); --model continua sobrescrevendo na hora de abrir. Para limitar as ferramentas que ele pode usar, use pi_args no config.json do bus:

{ "pi_args": "-t bash,read,edit,write" }

Como rodar um agente Kimi Code no time? v1.6

O Kimi Code é o quarto motor, e o mais flexível: ele importa um catálogo público com 190 provedores e mais de 6.700 modelos. Na prática, um só motor te dá GPT, Gemini, Qwen, DeepSeek, K3 e até modelo rodando na sua máquina — sem o bus precisar de código novo para cada um.

Abrindo

bus open --name kd --agent kimi-code --role dev --cwd C:\projeto

Ele trabalha em silencio, com uma aba mostrando cada entrega e a resposta — o mesmo modo do pi headless. A sessão dele nasce vazia: o Kimi recusa um id que ele mesmo não criou, então o bus abre a sessão na primeira entrega e guarda o id que voltar.

Com janela de verdade v1.7.1

bus open --name kd --agent kimi-code --tui --role dev --cwd C:\projeto

Abre a TUI do Kimi como o Grok abre a dele: você vê a conversa ao vivo. O Kimi não tem a ferramenta Monitor do Claude Code, mas acorda sozinho quando uma tarefa em background termina — então o agente arma bus watch --once em background, recebe a notificação na chegada da mensagem, responde e rearma. Por baixo, o bus semeia a sessão em modo headless (é o único modo em que o Kimi aceita um perfil de agente) e abre a janela retomando essa sessão.

Única diferença prática para o Grok: a janela abre esperando você. Digite pronto e Enter para ele armar o watch. --danger nesse modo passa -y ao Kimi. No bus setup, a pergunta “aba espelho ou TUI de verdade?” agora aparece também para agentes kimi-code.

Escolhendo o modelo

Uma linha no config.json do bus, valendo para todo agente kimi-code:

{ "kimi-code_args": "-m deepseek/deepseek-chat" }

Sem essa chave, vale o default_model do próprio Kimi (~\.kimi-code\config.toml).

Já tenho uma sessão aberta há horas. Dá para colocá-la no time? v1.6

Dá, e sem perder nada da conversa. O bus open abre uma sessão nova, do zero — se você já está a meio caminho de um trabalho, era o histórico inteiro que se perdia. O bus adopt resolve isso.

bus --ns meu-time adopt --name dev --role dev

Ele prepara o agente e imprime um bloco de texto. Você cola esse bloco dentro da sessão que já está aberta — e ela se registra sozinha.

Por que colar, e o bus não faz sozinho

O id de uma sessão Claude Code viva só existe dentro dela. Do seu terminal não há como ler. Então o registro parte de dentro; o comando só monta a instrução certa — e ela tem três detalhes que erram calado se forem digitados à mão: o código da sala (um identificador que você não teria como adivinhar), a sala em si, e o arquivo de personalidade que a sessão aberta nunca leu.

O que acontece depois

A sessão vira leitora: continua sua, o bus não a retoma por trás, e as mensagens do time chegam como linhas [BUS] dentro dela. Você segue trabalhando normalmente.

Como rodar dois times sem eles se misturarem? v1.2

Salas são redes independentes na mesma máquina: cada uma com seu registro, suas filas e seu próprio carteiro. Dois times podem usar o nome dev sem qualquer cruzamento.

bus --ns rcs start
bus --ns rcs open --name orq --role orquestrador --cwd C:\projetos\rcs
bus --ns rcs open --name dev --role dev --cwd C:\projetos\rcs --danger

bus --ns nio start                                        # outra sala, outro carteiro
bus --ns nio open --name dev --role dev --cwd C:\projetos\nio   # mesmo nome, zero conflito

bus rooms                                                 # todas as salas e seu estado

• --ns funciona antes ou depois do comando.
• Sem --ns nada muda — você segue na sala padrão, como sempre foi.
• A sessão aberta com bus open herda a sala automaticamente.

Como saber se uma tarefa delegada travou? v1.2

Entrega não é conclusão. Toda tarefa entregue fica em aberto até a resposta chegar na mesma conversa.

bus pending                        # o que foi delegado e nao voltou
bus pending --agent dev            # filtra por agente
bus nudge <msg-id>                 # cobra o devedor na mesma conversa
bus nudge --all --older-than 30    # cobra tudo parado ha +30min

PENDENCIAS ABERTAS
  ID                         DEVEDOR    CREDOR     IDADE    TAREFA
  m-20260726...-a1b2         dev        orq        47min    implementar endpoint /leads

O fechamento é automático: quando o agente responde na conversa, a pendência sai da lista.

Como verificar a saúde da rede? v1.2

bus doctor

Um comando verifica tudo e diz como corrigir cada item encontrado:

== bus doctor ==
[OK]  monitor rodando (pid 25680)
[!!]  'dev': 3 ouvintes vivos (deveria ser 1) -> rode: bus watch --stop dev
[!!]  1 conversa(s) bloqueada(s) -> rode: bus unblock <thread-id>

Tirar um agente do time

Fechar a janela não remove o agente. Ele continua no time apontando para uma sessão que não existe mais: mensagens novas se acumulam para ele e as tarefas que ele devia ficam paradas para sempre na lista de pendências.

bus remove <agente>            # tira do time, mantem o historico
bus remove <agente> --purge    # tira do time e apaga o historico dele

O comando faz a saída limpa, em ordem:

• encerra o ouvinte do agente (nenhum processo fica escutando à toa);
• arquiva a fila dele — nada é descartado em silêncio;
• cancela as tarefas que ele devia e avisa quem estava cobrando, para ninguém esperar resposta que não vem;
• tira do bus agents, mantendo o histórico para auditoria (salvo com --purge).

Outros comandos úteis:

bus sweep                     # limpa processos de bastidor que ficaram orfaos
bus blocked                   # conversas interrompidas pelo limite + como liberar
bus stop                      # para a sala: arquiva a fila e encerra os ouvintes
bus start                     # sobe limpa
bus start --resume-pending    # sobe retomando a fila arquivada

Como ver todos os agentes numa tela só?

O claude-bus integra com o herdr, um multiplexer de terminal pra agentes de IA. Rodando o bus open de dentro do herdr, cada agente abre como uma aba (workspace) do herdr — todos lado a lado, com status ao vivo (trabalhando / bloqueado / ocioso).

bus open --name dev1 --role dev --cwd C:\projetos\app --danger   # dentro do herdr = vira aba automaticamente

bus up meu-time --herdr-mode split                          # time inteiro lado a lado
bus open --name dev --herdr-mode split --split-direction down

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

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)

Ouvinte vivo não quer dizer agente vivo

O bus status mostra as duas coisas em colunas separadas, porque são fatos diferentes:

vivo + morta significa que o ouvinte sobreviveu à janela que caiu: o agente recebe mensagem e ninguém processa. Reabra com bus up <time>, ou tire de vez com bus remove <agente>. O bus doctor também acusa. desconhecida apenas quer dizer que o bus não conseguiu identificar a janela — não é problema.

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?