Como o HagiCode integra 13 Agent CLIs em um único sistema
Como o HagiCode integra 13 Agent CLIs em um único sistema
Na verdade, não é tão difícil, mas também não é tão simples. Vamos conversar sobre como usamos uma arquitetura em camadas para gerenciar de forma unificada Agent CLIs tão distintos quanto Claude Code, Codex, Copilot, Gemini, e ainda assim conseguir plugar um novo a qualquer momento.
Contexto
A história começou de repente, motivada por um problema bem incômodo.
Agent CLIs têm surgido como brotos de bambo nos últimos anos — Claude Code, OpenAI Codex, GitHub Copilot, Gemini CLI, Kimi, Qoder, Kiro… A cada poucos meses surge um novo. Como um projeto que quer que o usuário “instale um HagiCode e use todos os Agentes”, não podemos apostar tudo em um único CLI; ao mesmo tempo, não dá para escrever uma lógica completa de instalação, verificação de saúde e agendamento para cada CLI — o código incharia a ponto de ficar in manutenível, uma verdadeira bagunça que ninguém ousaria tocar.
O problema mais grave é que esses CLIs têm temperamentos bem diferentes: alguns usam stdio, outros gRPC, alguns fornecem apenas uma entrada shell, e os formatos de saída em streaming também são inconsistentes. Se escrevermos julgamentos diretos no código de negócio como if (provider == ClaudeCode), em menos de seis meses teremos um amontoado de “código legado” que ninguém se arriscará a mexer. Afinal, quem quer mexer em um tijolo que parece prestes a desmoronar?
Para conter todas essas dores, tomamos uma decisão: adicionar uma camada fina de abstração e um runtime compartilhado entre a camada de negócio e os CLIs específicos. Parece simples, mas isso determina diretamente a capacidade do HagiCode de integrar rapidamente novos CLIs. Em breve explico como fazer.
Sobre o HagiCode
A solução compartilhada aqui vem da nossa prática no projeto HagiCode. O HagiCode é uma plataforma de integração de assistentes de código IA com um objetivo bem direto — com uma única instalação, uma única configuração, conectar todos os Agent CLIs principais para uso dos usuários.
De onde vem o número “13”
Primeiro, um número que é frequentemente questionado — por que 13 Agent CLIs.
Na verdade, a resposta está escondida no enum AIProviderType, como as sombras de bambu fora da janela; basta olhar e você verá. A definição original é assim:
public enum AIProviderType{ ClaudeCodeCli = 0, CodexCli = 1, GitHubCopilot = 2, CodebuddyCli = 3, OpenCodeCli = 4, IFlowCli = 5, // Descontinuado HermesCli = 6, QoderCli = 7, KiroCli = 8, KimiCli = 9, GeminiCli = 10, DeepAgentsCli = 11, ReasonixCli = 12, PiCli = 13,}O enum tem 14 valores, mas o caminho IFlowCli=5 não funciona mais. Em AIProviderFactory, ele é explicitamente bloqueado:
if (providerType == AIProviderType.IFlowCli){ throw new NotSupportedException("IFlowCli is no longer supported");}Combinando com o filtro IsActivelySupportedProviderType(), o que realmente está “vivo” no sistema são exatamente 13: Claude Code, Codex, GitHub Copilot, CodeBuddy, OpenCode, Hermes, Qoder, Kiro, Kimi, Gemini, DeepAgents, Reasonix, Pi.
Eis a origem do “13”. Não é um número de marketing; é contado direto no código. Afinal, números não mentem; quem mente somos nós mesmos.
Arquitetura em camadas: trancando as mudanças
A ideia central para integrar 13 CLIs resume-se a uma frase: fazer com que o código de negócio não se importe com qual CLI está sendo chamado.
Dividimos isso em seis camadas, de cima para baixo:
1. Camada de identidade — AIProviderType
O enum é o “número de documento” de cada CLI. Em qualquer lugar em que um CLI é mencionado, usamos esse valor de enum; conversão entre string e enum é feita com ToStringValue() / ToAIProviderType(). Simples, mas indispensável.
2. Camada de contrato de negócio — IAIProvider / IAIProviderFactory
O lado de negócio reconhece apenas a interface IAIProvider, que define ações genéricas como “enviar um prompt e receber uma resposta em streaming”. O que está por baixo, se é Claude ou Codex, não interessa ao negócio — como enviar uma carta: você apenas a entrega; se o carteiro se chama Fulano, quem se importa?
3. Camada de adaptador — *CliProvider
Cada CLI tem um adaptador fino, como PiCliProvider, ReasonixCliProvider, ClaudeCodeCliProvider. O que esses adaptadores fazem é pouco: traduzir solicitações genéricas de negócio para parâmetros que o CLI específico entenda, e traduzir de volta a saída do CLI. Eles são propositalmente finos; adicionar um novo CLI é basicamente copiar um existente e ajustar.
4. Camada de runtime compartilhado — ICliProvider<TOptions>
Esta camada em HagiCode.Libs é onde o trabalho pesado realmente acontece: iniciar processos de forma multiplataforma, tratar transporte stdio, analisar saída em streaming, lidar com timeouts e repetições. Todos os adaptadores reutilizam o mesmo runtime, então ao integrar um novo CLI quase não é necessário reescrever a parte de gerenciamento de processos.
Uma analogia: a camada de adaptador é o “tradutor”; a camada de runtime compartilhado é a “empresa de entregas”. O tradutor apenas se preocupa em se fazer entender; como o pacote é entregue, se há trânsito, isso é com a empresa de entregas. Cada um no seu quadrado, o mundo fica mais tranquilo.
5. Camada de roteamento de fábrica — AIProviderFactory
Um switch em CreateProvider instancia o adaptador correspondente de acordo com AIProviderType, verificando também IsConfigured. Este é o único lugar que “sabe o tipo concreto”, estritamente isolado na fábrica. As mudanças só podem ocorrer em um canto, todo o resto permanece limpo.
6. Camada de projeção de diretório / UI — main-professions.yaml
Esta camada é interessante; não é código, é dado.
A lista de profissões principais (personagens como “sou frontend”, “sou backend”, “sou fullstack”) é acionada pelo arquivo predefinido main-professions.yaml, lido por HeroPrimaryProfessionPresetProvider e projetado na interface do usuário. Para adicionar uma nova profissão principal, não é necessário alterar uma linha de código; basta editar o YAML. Dados substituem código, tranquilidade garantida.
Aliás, este é o ponto de maior refactor do HagiCode. Nas versões iniciais havia um registro interno chamado
AgentCliInstallRegistry; depois percebemos que o custo de manutenção era muito alto — muito código, muito cansaço — então o conjunto inteiro foi derrubado e substituído por uma abordagem orientada a dados + verificação de saúde. É também por isso que o HagiCode consegue agora expandir rapidamente os tipos de profissões.
Como resolvemos a instalação
13 CLIs para instalar, cada um com um método oficial diferente — é outra montanha.
Nossa abordagem é pré-instalação via Docker Compose + garantia de gerenciamento externo. Na imagem, pré-instalamos os CLIs principais (Claude Code, Codex, Copilot, CodeBuddy, OpenCode, Qoder, Kiro, Kimi, Gemini, Pi); o usuário puxa a imagem e já usa, sem precisar digitar comando por comando. Com tudo instalado, o clima também melhora.
Para instalações separadas em ambiente local, a matriz de comandos de instalação é mais ou menos assim (verificado na documentação oficial):
| CLI | Instalação oficial |
|---|---|
| Claude Code | npm install -g @anthropic-ai/claude-code |
| Codex | npm install -g @openai/codex |
| GitHub Copilot | npm install -g @github/copilot |
| CodeBuddy | npm install -g @tencent-ai/codebuddy-code |
| OpenCode | npm i -g opencode-ai@latest |
| Qoder | npm install -g @qoder-ai/qodercli |
| Kiro | curl -fsSL https://cli.kiro.dev/install | bash |
| Kimi | curl -LsSf https://code.kimi.com/install.sh | bash |
| Gemini | npm |
| Hermes | Script oficial, mantemos docs-only como fallback |
| DeepAgents / Reasonix | Veja a documentação oficial de cada um |
O frontend PrimaryProfessionCard.tsx também acompanhou essa mudança — agora ele não tem um botão “instalar CLI”, mas exibe disponibilidade do CLI, resultados de detecção de versão e uma mensagem de fallback “este CLI é gerenciado externamente”. Ou seja, se dá para instalar ou não é responsabilidade da camada de sistema; a UI apenas reflete o estado com honestidade. Escrever estado e lógica separadamente vai acabar desalinhando, então por que fazer isso?
O que é preciso para adicionar um novo CLI
Na prática, adicionar um novo CLI no HagiCode se resume a alguns passos:
- Adicionar um valor ao enum
AIProviderType - Copiar um
*CliProviderexistente, ajustar parâmetros e análise de saída para o novo CLI - Adicionar uma linha de roteamento no
switchdeAIProviderFactory - Se for entrar no catálogo de profissões principais, configurar em
main-professions.yaml - Adicionar um comando de instalação na imagem (ou usar o gerenciamento externo como fallback)
Todo esse processo, as mudanças essenciais não passam de duzentas linhas de código — esse é o valor real dessa abstração. A cada novo CLI integrado, o custo marginal é baixo; nenhuma linha de código de negócio precisa ser alterada. Todos os caminhos levam a Roma, apenas o nosso caminho é um pouco mais fácil.
Conclusão
Olhando para trás, “integrar 13 CLIs” parece intimidante, mas desmembrando, são apenas duas competências:
Uma é isolar as mudanças — por meio do enum AIProviderType + contrato IAIProvider + adaptadores finos + runtime compartilhado, desacoplando o código de negócio dos CLIs específicos; a outra é tornar a configuração orientada a dados — usar predefinições YAML como main-professions.yaml para acionar diretórios e UI, evitando ter que alterar código a cada nova adição.
Esta solução foi estabilizada após algumas iterações e tropeços no desenvolvimento real do HagiCode. Se você está construindo um sistema semelhante de “integração de múltiplos providers”, espero que essa abordagem em camadas possa servir de referência. Afinal, Agent CLIs continuarão surgindo nos próximos anos; uma arquitetura que consiga integrar rapidamente novos CLIs é muito mais importante do que “quantos são suportados agora”…
开始使用 HagiCode
一次安装，几分钟上手
HagiCode for Windows 在 Microsoft Store 免费提供。打开商店即可安装并保持更新；也可以先对比各版本与定价，再决定从哪个渠道开始。