Implantação e Dicas do oh-my-claudecode: 32 Agentes Profissionais Trabalhando para Você, Eficiência Dobrada

Dificuldade: Intermediária | Duração: 30 minutos | Ganhos: Domínio de orquestração multi-agente, implantação zero-config e criação de pipelines de equipe

Público-alvo: Desenvolvedores que já utilizam ou planejam utilizar o Claude Code e desejam elevar a eficiência da colaboração entre agentes.

Dependências principais: Node.js ≥18, tmux (opcional multiplataforma), Claude Code CLI

---

1. Introdução ao Projeto

O Claude Code por si só já é poderoso, mas um único Agente muitas vezes tem dificuldades com projetos complexos de múltiplos módulos — você acaba tendo que alternar repetidamente entre várias janelas de chat ou coordenar manualmente revisões de código, design de arquitetura e validação de testes.

O oh-my-claudecode (doravante denominado OMC) foi criado para resolver esse problema. Ele é uma camada de orquestração multi-agente para o Claude Code, cujo conceito central é:

Don't learn Claude Code. Just use OMC.

Em termos simples, você só precisa descrever o que deseja em linguagem natural, e o OMC agendará automaticamente 32 Agentes profissionais, escolherá os modelos apropriados (Haiku / Sonnet / Opus) e processará as tarefas em paralelo até que a validação seja concluída. Todo o processo é zero-configuração, sem necessidade de memorizar comandos.

Endereço do Projeto: https://github.com/Yeachan-Heo/oh-my-claudecode

---

2. Visão Geral dos Recursos Principais

2.1 Pronto para Uso com Zero Configuração

Não é necessário escrever nenhuma configuração YAML ou JSON. Após a instalação, basta falar em linguagem humana para rodar. Os valores padrão inteligentes cobrem 90% dos cenários.

2.2 32 Agentes Profissionais

Cada Agente possui uma responsabilidade clara, e o OMC faz o roteamento automático para o Agente mais adequado conforme o tipo de tarefa:

A lista completa está definida em AGENTS.md.

2.3 Roteamento Inteligente de Modelos

O OMC seleciona automaticamente o modelo com base na complexidade da tarefa:

• Haiku: Buscas simples, formatação, pequenas alterações de texto
• Sonnet: Implementação padrão, depuração, testes (principal uso diário)
• Opus: Design de arquitetura, revisão de segurança, refatoração complexa

O benefício disso é a otimização de custos; o feedback da comunidade aponta uma economia média de 30-50% no consumo de tokens.

2.4 Paralelização Automática

Tarefas independentes são distribuídas automaticamente para diferentes Agentes para execução paralela, sem que você precise dividi-las manualmente.

2.5 Execução Persistente (Ciclo verify/fix)

No modo Ralph, após concluir a tarefa, o Agente entra automaticamente em um ciclo de validação — se a validação falhar, ele corrige a si mesmo e executa novamente até que realmente passe.

2.6 Autoaprendizado de Habilidades (Sistema Learner)

Experiências de depuração encontradas durante a execução são extraídas automaticamente em arquivos de Skill reutilizáveis, localizados em .omc/skills/. Na próxima vez que encontrar um problema similar, o contexto é injetado automaticamente — sem necessidade de lembrança manual.

2.7 Integração OpenClaw

Suporta o encaminhamento de eventos de sessão do Claude Code para o OpenClaw Gateway, permitindo notificações automatizadas e gatilhos remotos via canais como Telegram / Discord.

---

3. Estrutura Completa do Projeto

oh-my-claudecode/
├── agents/              # Arquivos de definição dos 32 Agentes profissionais
├── bridge/              # OpenClaw / Pontes de terceiros
├── docs/                # Docs de arquitetura, guias de migração, monitoramento de performance
├── examples/            # Fluxos de trabalho de exemplo
├── hooks/               # Injeção de hooks no Claude Code
├── missions/            # Definição de missões
├── research/            # Módulo de pesquisa
├── scripts/             # Scripts utilitários (Demo do OpenClaw Gateway, etc.)
├── skills/              # Arquivos de Skills nativos do OMC
├── src/                 # Código-fonte principal
├── tests/               # Suíte de testes
├── CLAUDE.md            # Configuração principal de runtime do Agente (injetada no Claude Code pelo OMC)
├── AGENTS.md            # Catálogo e descrição de Agentes
└── package.json

Para usuários comuns, a interação diária ocorre principalmente com:

• skills/ — Arquivos de Skills personalizados
• .omc/ — Sessões, estados e arquivos de plano gerados em tempo de execução

---

4. Instalação e Configuração

4.1 Pré-requisitos

Instalação Obrigatória:

• Claude Code CLI — Requer assinatura Max/Pro ou Anthropic API Key
• Node.js ≥18 — O OMC é um projeto TypeScript/npm

Opcional, mas Fortemente Recomendado:

• tmux — O recurso omc team e a recuperação automática de limite de taxa dependem do tmux

Instalação do tmux por plataforma:

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

# Arch
sudo pacman -S tmux

# Windows Nativo (Recomendado)
winget install psmux

# Windows WSL2
sudo apt install tmux

4.2 Instalando o OMC (Dois Métodos)

Método 1: Instalação via Marketplace (Recomendado)

# Adicionar fonte do plugin
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# Instalar o plugin
/plugin install oh-my-claudecode

Método 2: Instalação Global via npm

npm i -g oh-my-claude-sisyphus@latest

Após a instalação, o OMC será ativado automaticamente e todos os comandos / e palavras-chave mágicas estarão disponíveis.

4.3 Inicialização da Configuração

# Execute em qualquer diretório
/setup
/omc-setup

A primeira execução guiará você através de:

• Confirmação do diretório de configuração do Claude Code
• Configuração do OpenClaw Gateway (opcional)
• Detecção de sessão tmux

Se encontrar anomalias, execute a ferramenta de diagnóstico:

/omc-doctor

4.4 Habilitar o Team Mode (Recomendado)

O Team Mode é a forma de orquestração padrão após o OMC v4.1.7. É necessário habilitar recursos experimentais na configuração do Claude Code:

# Editar ~/.claude/settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

---

5. Análise Profunda dos Modos de Execução

O OMC oferece vários modos de execução adequados para diferentes cenários. Entender as diferenças é a chave para o uso eficiente.

5.1 Team Mode (Recomendado) ⭐

Cenário: Tarefas complexas de múltiplos módulos que exigem trabalho colaborativo de arquitetura, codificação, revisão e testes.

O Team Mode opera em uma pipeline rigorosa:

team-plan → team-prd → team-exec → team-verify → team-fix (ciclo)

A tarefa começa no planejamento, passa pelo design do produto, execução do código, validação, e volta para a fase de execução se problemas forem encontrados na fase de correção. Todo o processo é coordenado automaticamente pelo OMC.

Uso Básico:

/team 3:executor "Corrigir todos os erros de compilação TypeScript"

O número 3 indica o uso de 3 Agentes executor processando em paralelo.

tmux Workers via CLI (v4.4.0+):

omc team 2:codex "Revisar segurança do módulo de auth"
omc team 2:gemini "Redesenhar acessibilidade dos componentes de UI"
omc team 1:claude "Implementar fluxo de pagamento"
omc team status auth-review
omc team shutdown auth-review

Estes são processos tmux independentes reais que encerram automaticamente após a conclusão, sem consumir recursos extras.

5.2 Autopilot

Cenário: Requisitos claros, conclusão ponta-a-ponta de uma funcionalidade sem muita intervenção humana.

autopilot: construir uma API REST para gerenciamento de tarefas

No modo Autopilot, um único Agente Lead é responsável por todo o processo, do design à implementação, sem depender da pipeline.

5.3 Ralph (Modo Persistente)

Cenário: A tarefa deve ser concluída integralmente; não pode haver casos de "sair após conclusão parcial".

O modo Ralph inclui a capacidade paralela do Ultrawork adicionando um ciclo extra de verify/fix:

executor → verify → fix → verify (até passar)

ralph: refatorar módulo auth, exigindo que todos os testes passem

Se você notar que o Claude Code costuma sair quando "parece concluído", mas sem validação real, o Ralph é a solução.

5.4 Ultrawork (Paralelismo Máximo)

Cenário: Correções/refatorações em massa que exigem velocidade máxima.

ulw corrigir todos os erros de ESLint
ulw renomear todos os componentes para PascalCase

Todas as correções rodam em paralelo, sem esperar que a anterior termine para começar a próxima, ideal para processamento em lote de listas de problemas conhecidos.

5.5 /ccg Consultor de Três Modelos

Cenário: Necessidade de obter as perspectivas do Codex e Gemini simultaneamente, sintetizadas pelo Claude.

/ccg Review this PR — architecture (Codex) and UI components (Gemini)

Ele chama /ask codex + /ask gemini, e o Claude fica responsável pela síntese final. Ótimo para revisões conjuntas de backend+frontend.

5.6 Tabela Comparativa de Modos

---

6. Demonstração Prática

6.1 Cenário 1: Construindo uma API REST (Team Mode)

Suponha que queiramos construir uma API REST de gerenciamento de tarefas usando Team Mode:

/team 2:executor "Implementar API REST de tarefas com 4 endpoints CRUD, usando Express + TypeScript"

O OMC decomporá a tarefa automaticamente:

1. architect desenha a estrutura da API e modelo de dados
2. executor implementa as interfaces em paralelo
3. test-engineer escreve testes de integração
4. code-reviewer revisa o código
5. verifier executa os testes de validação

Você só precisa aguardar o resultado final.

6.2 Cenário 2: Correção Automática de Erros (Ultrawork)

ulw corrigir todos os erros de tipo TypeScript e avisos de ESLint

Ideal para pipelines de CI/CD ou limpeza rápida ao assumir projetos legados.

6.3 Cenário 3: Requisitos Indefinidos (Deep Interview)

Se você não tem certeza do que fazer:

/deep-interview "Quero criar um sistema de blog pessoal"

O Deep Interview usará perguntas socráticas para esclarecer requisitos: quem é o público, preferência de stack, necessidade de CMS, requisitos de SEO... esclareça tudo antes de começar para evitar retrabalho.

6.4 Cenário 4: Revisão Cruzada de Modelos (/ccg)

/ccg Revise a arquitetura backend deste PR com Codex e os componentes de UI com Gemini

6.5 Cenário 5: Recuperação Automática de Limite de Taxa (Rate Limit)

Quando a API do Claude atingir o limite de taxa:

omc wait          # Ver status atual e guia de recuperação
omc wait --start  # Iniciar daemon de recuperação automática
omc wait --stop   # Parar o daemon

---

7. Solução de Problemas Comuns

Q1: Comando /team inválido, erro "Team Mode não habilitado"

Causa: A variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS não foi definida.

Solução:

# Editar ~/.claude/settings.json e adicionar:
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Reinicie a sessão do Claude Code para surtir efeito.

---

Q2: omc team reporta erro relacionado ao tmux

Causa: Usuários de Windows não instalaram o tmux, ou o tmux não está no PATH.

Solução:

# Windows Nativo
winget install psmux

# macOS
brew install tmux

# Verificar instalação
tmux -V

Se instalado e o erro persistir, verifique se o diretório bin do psmux está no PATH do sistema.

---

Q3: Comandos OMC não funcionam após instalação via Marketplace

Causa: O cache do plugin não foi atualizado ou o caminho de instalação está incorreto.

Solução:

# Atualizar o clone do marketplace
/plugin marketplace update omc

# Reinicializar
/setup

# Rodar diagnóstico
/omc-doctor

---

Q4: Claude Code indica limite de taxa mas não recupera automaticamente

Causa: omc wait --start não foi executado ou não está rodando dentro de uma sessão tmux.

Solução:

# Certifique-se de executar dentro de uma sessão tmux
tmux new -s omc-watch
omc wait --start

O daemon rodará em segundo plano no tmux e retomará a sessão do Claude Code automaticamente após a recuperação.

---

Q5: Comportamento anômalo após atualizar o OMC

Causa: Incompatibilidade entre o cache do plugin antigo e o novo código.

Solução:

# Se instalado via Marketplace:
/plugin marketplace update omc
/setup

# Se instalado via npm:
npm i -g oh-my-claude-sisyphus@latest
/omc-doctor

---

Q6: Arquivo de Skill não injetado automaticamente

Causa: Palavras-chave de gatilho não conferem ou caminho do arquivo está errado.

Solução:

Arquivos de Skill podem estar em dois locais com prioridades diferentes:

# Nível de Projeto (Alta prioridade): .omc/skills/
# Nível de Usuário (Baixa prioridade): ~/.omc/skills/

Certifique-se de que o array triggers no frontmatter do arquivo Skill contenha palavras-chave da conversa atual:

---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]  # Correspondência de palavras-chave
source: extracted
---

---

8. Leituras Adicionais / Direções Avançadas

8.1 Escrita de Skills Personalizadas

O OMC permite extrair Skills reutilizáveis de experiências reais de depuração:

/learner

Isso gera arquivos YAML em .omc/skills/. Eles serão injetados automaticamente em problemas futuros, sem necessidade de recall manual.

8.2 Integração OpenClaw

O OMC pode encaminhar eventos de sessão do Claude Code para o OpenClaw Gateway para gatilhos e notificações remotas:

# Guia de configuração automática
/oh-my-claudecode:configure-notifications
# → Selecione "OpenClaw Gateway"

Configuração manual em ~/.claude/omc_config.openclaw.json:

{
  "enabled": true,
  "gateways": {
    "my-gateway": {
      "url": "https://your-gateway.example.com/wake",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "method": "POST",
      "timeout": 10000
    }
  },
  "hooks": {
    "session-start": { "gateway": "my-gateway", "instruction": "Session started for {{projectName}}", "enabled": true },
    "stop":          { "gateway": "my-gateway", "instruction": "Session stopping for {{projectName}}", "enabled": true }
  }
}

Eventos de hook suportados incluem: session-start, stop, keyword-detector, ask-user-question, pre-tool-use, post-tool-use.

8.3 Sistema de Notificações (Telegram / Discord / Slack)

omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678"

Envia automaticamente um resumo para o grupo ao encerrar a sessão, suportando tags incrementais.

8.4 Fluxo de Trabalho Colaborativo OpenClaw + OMC

Combinando a automação do OpenClaw com a orquestração multi-agente do OMC, você pode:

• OpenClaw escuta mensagens no Discord/Telegram e inicia uma sessão do Claude Code
• OMC orquestra 32 Agentes dentro do Claude Code para realizar tarefas complexas
• OpenClaw Gateway envia os resultados de volta para o canal de chat

Assim, você tem um assistente multi-agente 24 horas por dia, comandado via ferramentas de chat comuns.

Consulte scripts/openclaw-gateway-demo.mjs para aprender como montar esta arquitetura.

8.5 Monitoramento de Performance e Depuração

O OMC gera vários arquivos em .omc/ durante a execução:

.omc/sessions/*.json        # Resumos de sessão
.omc/state/agent-replay-*.jsonl  # Logs de reprodução de execução
.omc/plans/                 # Planos de tarefas
.omc/research/              # Saídas de pesquisa

Execute o HUD para visualizar o status de orquestração em tempo real:

/oh-my-claudecode:hud setup
omc hud

---

Links de Referência

• Página do Projeto: https://github.com/Yeachan-Heo/oh-my-claudecode
• Pacote npm: https://www.npmjs.com/package/oh-my-claude-sisyphus
• Documentação Completa: https://yeachan-heo.github.io/oh-my-claudecode-website
• Referência CLI: https://yeachan-heo.github.io/oh-my-claudecode-website/docs.html#cli-reference
• Comunidade Discord: https://discord.gg/PUwSMR9XNk