Guia Técnico · 2026 · V5.0.3

Instale o AIOX

Configure Claude Code, Codex CLI e Gemini CLI com o framework Synkra AIOX — a equipe ágil de agentes IA que transforma seu fluxo de desenvolvimento.

Claude Code Codex CLI Gemini CLI AIOX Core MCP Ecosystem Editores de Código

FASE 1

Pré-requisitos

FASE 2

CLI Tools

FASE 3

AIOX Core

FASE 4

MCP e Plugins

FASE 5

IDE Editores

FASE 6

Primeiro Uso

Requisitos do Sistema

Verifique antes de começar

Requisito	Versão mínima	Observação
Node.js	≥ 18.0.0	v22 LTS recomendado — instale via NVM
npm	≥ 9.0.0	Já vem com o Node.js — ou use yarn / pnpm
RAM	4 GB+	8 GB recomendado
Sistema Operacional	macOS 10.15+ / Win 10+ / Linux	WSL recomendado no Windows

Claude Code tem instalador nativo Não requer Node.js. Mas AIOX (via npx) e Codex/Gemini CLI precisam de Node.js ≥ 18 (recomendado v22 LTS via NVM). Se usar tudo junto, instale Node.js primeiro.

WSL no Windows

Ambiente Linux recomendado para AIOX

Usuários Mac/Linux podem pular esta seção. WSL (Windows Subsystem for Linux) é o ambiente recomendado para Windows. Ele garante compatibilidade total com as ferramentas do ecossistema AIOX.

Abra o PowerShell como Administrador

Clique com botão direito no menu Iniciar → Windows PowerShell (Admin)

Instale o WSL com Ubuntu

powershell

wsl --install -d Ubuntu

Reinicie o computador

O Ubuntu abrirá automaticamente pedindo usuário e senha na primeira vez.

Instale Node.js no WSL

bash — dentro do terminal Ubuntu/WSL

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install --lts

# Verificar
node -v # deve mostrar v22.x.x
npm -v

Performance no Windows: Mantenha seus projetos no diretório home do Linux (~/projetos/) e não em /mnt/c/.... O I/O é significativamente mais rápido.

Instalar Node.js

Necessário para AIOX Core, Codex CLI e Gemini CLI

🟢 Node.js

É o motor de execução do JavaScript fora do navegador. Pense nele como o "motor de um carro" — é o que faz o JavaScript rodar na sua máquina.

📦 npm (Node Package Manager)

É o gerenciador de pacotes que vem junto com o Node.js. É como a "loja de peças" do carro — você usa para instalar bibliotecas e ferramentas.

Usuários Windows com WSL: o Node.js já foi instalado no passo 4 da seção anterior (dentro do Ubuntu). Podem avançar direto para a seção 4.

bash — Ubuntu / Debian / WSL

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install --lts

# Verificar
node -v # deve mostrar v22.x.x (LTS mais recente)
npm -v

bash — macOS via Homebrew

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc

nvm install --lts

# Verificar
node -v # deve mostrar v22.x.x (LTS mais recente)
npm -v

powershell

winget install OpenJS.NodeJS.LTS

# Verificar (abra um novo terminal após instalar)
node --version
npm --version

O Node.js instalado no Windows nativo não é acessível dentro do WSL. Se for usar WSL, instale o Node.js dentro do terminal Ubuntu (seção 2, passo 4).

Por que NVM? O NVM instala o Node.js no espaço do usuário — sem sudo, sem conflito de versões. O --lts sempre pega a versão LTS mais estável disponível.

O que é CLI?

Command Line Interface — Interface de Linha de Comando

É quando você controla um programa digitando comandos de texto no terminal, em vez de clicar em botões numa tela.

	Interface Visual (GUI)	CLI
O que é	Janelas, botões, ícones	Texto puro no terminal
Exemplo	Abrir o VS Code clicando	code . no terminal
Quem usa	Qualquer pessoa	Desenvolvedores

Analogia simples:
GUI é como dirigir um carro automático — intuitivo, visual.
CLI é como pilotar com câmbio manual — mais controle, mais velocidade, curva de aprendizado maior.

Ferramentas CLI essenciais

Além do Node.js, o AIOX usa o GitHub CLI (para PRs, CodeRabbit e controle de versão) e o Vercel CLI (para deploy de páginas e projetos). Instale ambos antes de continuar.

GitHub CLI gh

Gerencia repositórios, PRs e issues direto no terminal — necessário para CodeRabbit e @devops

bash — Ubuntu / Debian / WSL

# Adicionar repositório oficial do GitHub CLI
sudo apt-get update
sudo apt-get install -y curl

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

sudo apt-get update
sudo apt-get install -y gh

bash — macOS (Homebrew)

brew install gh

powershell — Windows

winget install GitHub.cli

Autenticar no GitHub

bash — login (abre o browser)

gh auth login
# Escolha: GitHub.com → HTTPS → Login with a web browser
# Copie o código, cole no browser e autorize

# Verificar autenticação:
gh auth status

Vercel CLI

Deploy de páginas e projetos, gerenciamento de domínios e variáveis de ambiente

bash — instalar globalmente (todas as plataformas)

# Instalar via npm (requer Node.js)
npm install -g vercel

Autenticar na Vercel

bash — login (abre o browser)

vercel login
# Abre o browser — faça login com GitHub, GitLab ou email

# Verificar autenticação:
vercel whoami

Conta gratuita: a Vercel tem um plano hobby gratuito que é suficiente para projetos pessoais e de estudo. Crie sua conta em vercel.com/signup.

Verificação rápida: após instalar tudo, confirme que os 3 CLIs estão disponíveis:

bash — verificar instalação

node -v       # deve mostrar v22.x.x
gh --version  # deve mostrar gh version 2.x.x
vercel -v     # deve mostrar vercel 5x.x.x

Claude Code

CLI oficial da Anthropic — melhor compatibilidade com AIOX

Claude Code tem paridade de hooks completa com o AIOX É o CLI de referência para automação máxima de contexto, guardrails e auditoria. Se você vai usar apenas um CLI, use Claude Code.

bash

# Instalar Claude Code
npm install -g @anthropic-ai/claude-code

# Verificar instalação
claude --version

# Iniciar (vai pedir login Anthropic)
claude

bash

# No terminal WSL/Ubuntu
npm install -g @anthropic-ai/claude-code

# Verificar
claude --version

Após instalar, abra claude no terminal. Ele vai abrir o processo de autenticação com a Anthropic. Você precisa de uma conta em claude.ai.

Sync dedicado de agentes: O arquivo .claude/CLAUDE.md é carregado automaticamente. Para sincronizar agentes com o Claude Code após instalar o AIOX, use: npm run sync:ide:claude

Codex CLI Opcional

CLI da OpenAI — paridade parcial com AIOX

bash

# Instalar Codex CLI
npm install -g @openai/codex

# Verificar
codex --version

# Iniciar (login com conta ChatGPT — abre no browser)
codex

Incluso na sua assinatura ChatGPT. O Codex CLI autentica direto com sua conta ChatGPT — sem configurar chaves. Ao rodar codex pela primeira vez, ele abre o login no browser. Por tempo limitado, também disponível nos planos Free e Go.

Plano ChatGPT	Acesso ao Codex CLI
Free / Go	✅ Incluso (por tempo limitado)
Plus	✅ Incluso
Pro	✅ Incluso (limites maiores)
Business / Enterprise / Edu	✅ Incluso

Paridade parcial com AIOX: Algumas automações dependem do AGENTS.md, /skills e MCP. Ativação de agentes usa /skills em vez de @agent-name.

Gemini CLI Opcional

CLI do Google — alta paridade com AIOX

bash

# Instalar Gemini CLI
npm install -g @google/gemini-cli

# Verificar
gemini --version

# Iniciar (login com conta Google — abre no browser)
gemini

Gratuito com conta Google pessoal. O Gemini CLI autentica com sua conta Google — sem configurar chaves. Ao rodar gemini pela primeira vez, ele abre o login no browser. O free tier já inclui acesso ao Gemini 2.5 Pro com janela de 1M tokens.

Plano	Limites no Gemini CLI	Preço
Conta Google (grátis)	60 req/min · 1.000 req/dia	Grátis
Google AI Pro	Limites maiores (ideal para uso diário)	~US$ 19,99/mês
Google AI Ultra	Limites mais altos + prioridade	~US$ 249,99/mês

Gemini CLI tem alta paridade de hooks com AIOX. Ativação de agentes usa /aiox-menu → /aiox-<agent>. Boa cobertura de automações pre/post tool e sessão.

Repositórios Synkra AIOX

O ecossistema open source do AIOX

Organização SynkraAI no GitHub Todos os repositórios AIOX são open source e estão em github.com/SynkraAI.

aiox-core

SynkraAI / aiox-core

Framework principal. Contém todos os agentes, workflows, tasks e templates do AIOX. Instale com npx aiox-core.

Obrigatório npm package v5.0.3 ⭐ 2.1k

mcp-ecosystem

SynkraAI / mcp-ecosystem

Configurações MCP prontas. Presets para desenvolvimento, pesquisa e full. Configs para Claude Code e Cursor.

Opcional configs

SynkraAI

github.com / SynkraAI

Organização completa. Issues, discussions, roadmap e todos os projetos do ecossistema Synkra AIOX — incluindo aiox-core e mcp-ecosystem.

Organização

Instalar AIOX Core Principal

Um comando instala tudo — você só roda npx uma vez

npx é só na instalação. Você roda npx aiox-core init apenas uma vez para criar o projeto. Depois disso, o AIOX já está instalado localmente e você usa os agentes direto na IDE (Claude Code, Cursor, etc.) sem precisar rodar npx novamente. Pense no npx como o instalador de um programa — você usa uma vez e depois abre o programa normalmente.

bash

# Criar novo projeto com assistente interativo
npx aiox-core init meu-projeto

# Ou com versão específica
npx aiox-core@latest init meu-projeto

bash

# Instalar em projeto existente
cd seu-projeto
npx aiox-core install

# O instalador detecta automaticamente sua configuração

bash

# Upstream Auto-Update — atualiza sem perder customizações
npx aiox-core@latest install

# Simular antes (ver o que muda sem aplicar nada)
npx aiox-core install --dry-run

# Verificar saúde após atualizar
npx aiox-core doctor

# Corrigir problemas automaticamente (se houver)
npx aiox-core doctor --fix

O que o updater faz automaticamente: detecta a instalação existente, faz backup das suas customizações em .aiox-backup/, atualiza apenas os arquivos do core que mudaram e preserva suas configurações, squads e templates personalizados.

O que o instalador faz

Download da versão mais recente do NPM

Assistente interativo com @clack/prompts (escolha de IDE, gerenciador de pacotes)

Configuração automática do IDE (Codex CLI, Cursor ou Claude Code)

Setup de todos os agentes e workflows AIOX no projeto

Criação dos arquivos de configuração necessários

Inicialização do sistema de meta-agentes

Verificações de saúde do sistema

Suporte a Windows, macOS e Linux

Estrutura instalada

estrutura

meu-projeto/
├── .aiox-core/          # Framework AIOX (não modificar)
│   ├── development/
│   │   ├── agents/          # Agentes: @dev, @qa, @architect, @pm...
│   │   ├── tasks/           # Tasks executáveis
│   │   └── templates/       # Templates de docs
│   ├── core/                # Configuração central
│   ├── hooks/               # Hooks de ciclo de vida
│   └── workflows/           # Workflows multi-step
├── .claude/             # Integração Claude Code
├── .codex/              # Integração Codex CLI
├── .gemini/             # Integração Gemini CLI
├── docs/
│   └── stories/             # Stories de desenvolvimento
├── squads/              # Squads customizados
└── packages/            # Pacotes compartilhados

Verificar instalação

Após instalar, confirme que tudo está funcionando:

bash

npx aiox-core doctor

# Se houver problemas, corrija automaticamente:
npx aiox-core doctor --fix

saída esperada

🏥 AIOX System Diagnostics
✔ Node.js version: v22.x.x (meets requirement: >=18.0.0)
✔ npm version: 10.x.x
✔ Git installed
✔ Synkra AIOX: v5.0.3
✔ .aiox-core/ directory exists
✔ Agent files found
✔ Workflow files found
✅ All checks passed! Your installation is healthy.

MCP Ecosystem Opcional

Servidores MCP que ampliam as capacidades do Claude Code

MCPs opcionais do AIOX

Os MCPs não estão incluídos no npx aiox-core install. São ferramentas separadas que ampliam as capacidades do Claude Code. O AIOX funciona 100% sem eles — instale apenas quando quiser capacidades extras.

MCP	Chave API?	Para que serve	Agente AIOX
context7	❌ Não	Documentação atualizada de bibliotecas para LLMs	@dev
desktop-commander	❌ Não	Gerenciamento de arquivos e comandos de terminal	@dev
playwright	❌ Não	Automação de browser para testes	@qa
exa	✅ Sim (free tier)	Busca web com IA e extração de conteúdo	@analyst
github	✅ Sim (PAT)	Gerencia repositórios, issues, PRs e branches via prompt	@devops
vercel	✅ Sim (OAuth)	Gerencia deployments, logs, projetos e domínios via prompt	@devops

Recomendação para iniciantes: instale apenas context7 e desktop-commander (sem chave API, zero configuração extra). Os demais são para uso avançado.

Escopos do MCP (Claude Code)

O Claude Code usa um sistema de escopos para saber onde salvar cada configuração de MCP. Entender isso evita confusão na hora de instalar. Gemini CLI e Codex CLI têm seus próprios formatos — veja as abas de instalação abaixo.

Estrutura de pastas no seu ambiente

estrutura

~/meu-usuario/          ← onde o Claude Code está instalado (escopo global)
└── meu-projeto/        ← onde o AIOX está instalado (escopo project)

Os dois escopos principais

Escopo	Flag	Arquivo	Disponível em
user (global)	--scope user	~/.claude.json	Todos os projetos
project	--scope project	.mcp.json na raiz do projeto	Só aquele projeto

Regra de carregamento: ao iniciar o Claude Code dentro de meu-projeto, ele carrega primeiro o global (~/.claude.json) e depois o project (.mcp.json). Tudo que está no global fica disponível automaticamente — sem nenhuma configuração extra no projeto.

Como instalar os MCPs

Cada CLI tem seu próprio sistema de configuração de MCPs. Os comandos de instalação não são intercambiáveis entre Claude Code, Gemini CLI e Codex CLI. Escolha a aba correspondente ao CLI que você está usando.

Usa claude mcp add --scope user → salva em ~/.claude.json. Disponível globalmente em qualquer projeto:

bash — Claude Code

# context7 — documentação de bibliotecas para LLMs
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp

# desktop-commander — gerenciamento de arquivos e terminal
claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander

# playwright — automação de browser para testes
claude mcp add --scope user playwright -- npx -y @playwright/mcp

# exa — busca web com IA (requer chave API de exa.ai — free tier disponível)

# Passo 1: abrir o .bashrc
nano ~/.bashrc
# Adicionar no final do arquivo:
export EXA_API_KEY=sua_chave_aqui
# Salvar: Ctrl+O → Enter → Ctrl+X

# Passo 2: ativar
source ~/.bashrc

# Passo 3: adicionar o MCP
claude mcp add --scope user exa -e EXA_API_KEY=$EXA_API_KEY -- npx -y exa-mcp

Como obter sua chave: crie uma conta em exa.ai (free tier: 1.000 buscas/mês). A chave fica salva no .bashrc localmente — nunca é exposta no chat ou commitada no repositório.

Vercel MCP — MCP remoto (OAuth)

O Vercel MCP usa OAuth — não precisa gerar token manualmente. O login é feito uma única vez pelo browser usando sua conta Vercel.

bash — Vercel MCP (Claude Code)

# vercel — gerenciamento de deployments, logs e projetos (requer autenticação OAuth)

# Passo 1: adicionar o MCP
claude mcp add --transport http vercel https://mcp.vercel.com --scope user

# Passo 2: abrir uma sessão do Claude Code
claude

# Passo 3: autenticar com sua conta Vercel
/mcp
# Vai abrir o browser — faça login com sua conta Vercel e autorize o acesso
# Após autorizar, feche o browser e volte ao terminal

Com o Vercel MCP configurado você consegue via prompt: ver status de deployments, analisar logs de erro, gerenciar projetos e domínios.

Teste rápido: abra uma sessão com claude e peça: "Liste meus projetos na Vercel". Se retornar os dados, está configurado corretamente.

GitHub MCP — MCP remoto

Diferente dos outros MCPs, o GitHub MCP é um MCP remoto — conecta via HTTP diretamente ao servidor do GitHub, sem instalar nada localmente. Requer um Personal Access Token (PAT).

bash — GitHub MCP (Claude Code)

# github — gerenciamento de repositórios, issues e PRs (requer Personal Access Token)

# Passo 1: abrir o .bashrc
nano ~/.bashrc
# Adicionar no final do arquivo:
export GITHUB_PAT=seu_token_aqui
# Salvar: Ctrl+O → Enter → Ctrl+X

# Passo 2: ativar
source ~/.bashrc

# Passo 3: adicionar o MCP
claude mcp add-json github "{\"type\":\"http\",\"url\":\"https://api.githubcopilot.com/mcp\",\"headers\":{\"Authorization\":\"Bearer $GITHUB_PAT\"}}" --scope user

Como gerar seu token: github.com → Settings → Developer settings → Personal access tokens → Tokens (classic). Marque as permissões: repo, read:org e workflow. O token fica salvo localmente — nunca é exposto no chat ou commitado no repositório.

Nota técnica: o GitHub MCP é um MCP remoto — conecta via HTTP diretamente ao servidor do GitHub, sem instalar nada localmente. O pacote @modelcontextprotocol/server-github foi depreciado em abril de 2025 e não deve ser usado.

Teste rápido: abra uma sessão do Claude Code com claude e peça: "Liste meus repositórios do GitHub". Se retornar a lista dos seus repos, está configurado corretamente. Se der erro de autenticação, o token está errado ou expirado.

Verificar MCPs instalados

bash

claude mcp list              # listar todos os MCPs
claude mcp get context7     # detalhes de um MCP específico
claude mcp get github       # verificar configuração do GitHub MCP
claude mcp get vercel       # verificar configuração do Vercel MCP

O Gemini CLI usa um arquivo de configuração próprio (settings.json) e não tem comando mcp add — você edita o JSON manualmente:

~/.gemini/settings.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "exa": {
      "command": "npx",
      "args": ["-y", "exa-mcp"],
      "env": { "EXA_API_KEY": "sua-chave-aqui" }
    }
  }
}

Crie o diretório se não existir: mkdir -p ~/.gemini e depois crie o arquivo settings.json com o conteúdo acima.

O Codex CLI tem sua própria sintaxe de comando — similar ao Claude Code mas com codex mcp add:

bash — Codex CLI

# context7 — documentação de bibliotecas para LLMs
codex mcp add context7 -- npx -y @upstash/context7-mcp

# desktop-commander — gerenciamento de arquivos e terminal
codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander

# playwright — automação de browser para testes
codex mcp add playwright -- npx -y @playwright/mcp

# exa — busca web com IA (requer chave API de exa.ai)
codex mcp add exa --env EXA_API_KEY=sua-chave-aqui -- npx -y exa-mcp

Nunca cole tokens ou chaves diretamente nos comandos. Use variáveis de ambiente no .bashrc (como nos exemplos de Exa e GitHub acima). As chaves ficam salvas localmente — nunca são expostas no chat ou commitadas no repositório.

Consumo de tokens e contexto

Cada MCP carregado injeta as definições dos seus tools no contexto da sessão — isso consome tokens. Quanto mais MCPs ativos, mais contexto ocupado antes mesmo de você digitar qualquer coisa.

Tool Search — otimização automática

O Claude Code tem um recurso chamado Tool Search que resolve isso automaticamente: em vez de carregar todos os tools de todos os MCPs de uma vez, ele carrega apenas os tools relevantes para cada tarefa.

~72k

tokens sem Tool Search

~8.7k

tokens com Tool Search

-85%

redução automática

Ativa sozinho quando os tools ocupam mais de 10% do contexto.

Conclusão prática: instale os MCPs que você realmente usa. O Tool Search cuida do resto.

CodeRabbit — Plugin de Code Review Destaque

Plugin de revisão automática de código com IA — integrado ao Claude Code

CodeRabbit é um plugin do Claude Code, não um MCP.
Plugins adicionam slash commands (/coderabbit:review) diretamente no CLI — diferente dos MCPs que adicionam tools de backend.

O que é um PR (Pull Request)? É uma solicitação para incluir suas alterações de código no repositório principal do projeto. Funciona assim: você trabalha numa cópia separada (branch), e quando termina, abre um PR pedindo que as mudanças sejam revisadas e aprovadas antes de entrar no código principal. É onde o time (ou o CodeRabbit) revisa a qualidade do código.

Integrado na camada 2 dos Quality Gates do framework AIOX

O CodeRabbit está na Layer 2 dos Quality Gates do AIOX:

Layer 1 (Local): pre-commit hooks, linting, type checking
Layer 2 (CI/CD): testes automatizados + CodeRabbit review ← aqui
Layer 3 (Human): revisão de arquitetura, aprovação final

Pré-requisito: o projeto precisa ser um repositório Git (git init ou git clone). CodeRabbit não funciona fora de repositórios Git.

Duas formas complementares de uso

1. GitHub App (automático nos PRs)

Quando o @devops abre um PR, o CodeRabbit revisa automaticamente — sem nenhum comando.

2. CLI + Plugin (loop local com Claude Code)

O @dev implementa, revisa, corrige e só entrega quando o review estiver limpo.

Agentes AIOX que usam o CodeRabbit

Agente	Como usa	Quando
@dev (Dex)	Executa review local via CLI antes de entregar	Durante implementação — loop de auto-correção (max 2 iterações)
@qa (Quinn)	Valida se os findings do CodeRabbit foram resolvidos	No QA Gate — verifica qualidade do código entregue
@devops (Gage)	Review automático nos PRs via GitHub App	Ao abrir PR — CodeRabbit revisa automaticamente sem comando

O CodeRabbit está integrado no Story Development Cycle (SDC): @dev revisa localmente → @qa valida no gate → @devops recebe review automático no PR.

Como funciona o fluxo de review

O CodeRabbit não altera código — ele apenas revisa e aponta problemas. Quem corrige é o @dev. Funciona como um code reviewer humano, mas automático e com IA.

@dev implementa o código

Desenvolve a feature ou fix conforme a story

@dev roda /coderabbit:review

Review local via CLI — analisa o código antes de entregar

CodeRabbit retorna findings

Lista de problemas: bugs, code smells, vulnerabilidades, melhorias

@dev corrige os findings self-healing loop

Lê cada finding, corrige o código e roda review novamente (máx. 2 iterações)

Review limpo → entrega para @qa

Código passa para o QA Gate — @qa valida se os findings foram resolvidos

@devops abre o PR

CodeRabbit revisa automaticamente via GitHub App — segunda camada de review

↩

Findings críticos no PR? → volta para @dev

Se o CodeRabbit encontrar problemas no PR, o @dev é chamado de volta para corrigir

Pré-requisito — dependências do sistema

Antes de instalar o CodeRabbit, garanta que as dependências básicas estejam presentes no seu sistema (especialmente no WSL/Ubuntu):

bash — instalar dependências do sistema

sudo apt-get update && sudo apt-get install -y unzip curl git

Instalação — passos comuns (todas as CLIs)

Cada CLI tem sua própria forma de integrar o CodeRabbit. Os passos 1 e 2 (instalar CLI + autenticar) são iguais para todos. O passo 3 (integração com a CLI de IA) muda conforme o tool que você usa.

Instalar o CLI do CodeRabbit (todas as CLIs)

bash

curl -fsSL https://cli.coderabbit.ai/install.sh | sh

Autenticar (todas as CLIs)

bash

coderabbit auth login
# Abre o browser para login com conta GitHub ou Google

Conectar ao repositório GitHub (todas as CLIs)

Acesse https://coderabbit.ai → login com GitHub → autorize o repositório. A partir daí, todo PR recebe review automático.

Integração por CLI

Cada CLI de IA integra o CodeRabbit de forma diferente. Escolha a aba correspondente:

O Claude Code usa o sistema de plugins — o CodeRabbit é instalado como plugin nativo e adiciona slash commands diretamente no CLI:

bash — instalar plugin

claude plugin install coderabbit
# Ou dentro do Claude Code:
# /plugin install coderabbit

Comandos disponíveis após instalação

bash — slash commands

/coderabbit:review               # revisa todas as mudanças
/coderabbit:review uncommitted   # só mudanças não commitadas
/coderabbit:review committed     # só mudanças commitadas
/coderabbit:review --base main   # compara com main

Ou em linguagem natural — basta pedir ao Claude:

linguagem natural

"Revise meu código antes de commitar"
"Verifique se há problemas de segurança nas minhas mudanças"

O Gemini CLI não tem sistema de plugins. O CodeRabbit é usado como ferramenta CLI independente — você roda os comandos diretamente no terminal:

bash — uso direto do CLI

# Revisar mudanças não commitadas
coderabbit review --uncommitted

# Revisar mudanças commitadas
coderabbit review --committed

# Comparar com branch main
coderabbit review --base main

Dica: você pode pedir ao Gemini CLI para rodar o comando coderabbit review em linguagem natural. Ele executa como qualquer outro comando de terminal.

O Codex CLI também não tem sistema de plugins. Use o CodeRabbit como CLI independente no terminal:

bash — uso direto do CLI

# Revisar mudanças não commitadas
coderabbit review --uncommitted

# Revisar mudanças commitadas
coderabbit review --committed

# Comparar com branch main
coderabbit review --base main

Dica: peça ao Codex para executar coderabbit review — ele roda o comando no terminal integrado.

O loop autônomo com AIOX

exemplo de instrução ao @dev

@dev Implemente a STORY-42. Ao terminar, rode /coderabbit:review,
     corrija todos os problemas críticos e só então conclua.

O agente implementa → revisa → corrige → repete até passar → entrega. Você só entra para aprovar o PR final.

Plano gratuito: o plugin funciona completamente no tier gratuito. Repositórios open source têm CodeRabbit sempre gratuito.

IDE Editores de Código Opcional

Configure seu editor com IA — compatibilidade e passo a passo de instalação

O que é uma IDE?

Integrated Development Environment — Ambiente de Desenvolvimento Integrado

É um programa que reúne tudo que um desenvolvedor precisa em um só lugar: editor de texto, terminal, debug, controle de versão (Git) e — nos IDEs modernos — IA integrada.

	Editor de texto simples	IDE
O que faz	Edita arquivos de texto	Edita, roda, debuga e versiona
Terminal integrado	Não tem	Sim — dentro do editor
IA embutida	Não tem	Sim (Cursor, Windsurf, AntiGravity)
Exemplos	Notepad, Sublime Text	VS Code, Cursor, Windsurf, AntiGravity

Como IDE e CLI se complementam no AIOX:
Você usa a IDE para visualizar e editar o código — e o Claude Code na CLI (terminal integrado da própria IDE) para orquestrar agentes, rodar stories e fazer deploys.
O fluxo é: IDE aberta → terminal integrado → claude → agentes AIOX em ação.

Todos os editores rodam no Windows — não no WSL. Instale e abra os IDEs pelo Windows normalmente. O terminal integrado de cada editor pode ser apontado para o WSL quando necessário.

O AIOX roda no terminal, não no editor. Editores com IA funcionam como complemento — a execução de agentes, stories e workflows acontece sempre na CLI. Use o editor para edição e a CLI para orquestração.

AntiGravity by Google Recomendado pelo AIOX

IDE agêntica do Google — 16 agentes especializados, MCP Store integrada e suporte a múltiplos modelos (Gemini, Claude, GPT). Gratuita na preview pública.

Por que AntiGravity? É uma IDE agent-first com orquestração nativa de agentes. Suporta MCP servers via MCP Store integrada, lê o AGENTS.md e o GEMINI.md gerados pelo AIOX, e funciona com Gemini + Claude + GPT simultaneamente.

Configuração — 3 passos

Baixar e instalar o AntiGravity

Acesse antigravity.google/download e execute o instalador. Disponível para Windows, macOS e Linux. Autenticação com conta Google (Gmail pessoal aceito).

Configurar MCP no AntiGravity

O AntiGravity tem sua própria configuração de MCP — separada do Claude Code.

Caminho na UI: Agent session → menu "..." → MCP Servers → Manage MCP Servers
Arquivo de config: ~/.gemini/antigravity/mcp_config.json
Também possui uma MCP Store integrada para buscar e instalar servidores diretamente.

O AntiGravity não lê o ~/.claude.json. Os MCPs precisam ser configurados separadamente no arquivo ~/.gemini/antigravity/mcp_config.json.

Verificar o AGENTS.md no projeto

O AntiGravity lê o AGENTS.md e o GEMINI.md na raiz do projeto — ambos já gerados pelo AIOX.

Lifecycle hooks do Claude Code (PreToolUse, PostToolUse) não são suportados no AntiGravity. Use os workflows nativos do editor para automações equivalentes.

VS Code

O editor mais popular — suporte ao AIOX via extensão Claude Code oficial da Anthropic

Baixar o VS Code

Acesse code.visualstudio.com e baixe para seu sistema operacional. Disponível para Windows, macOS e Linux (.deb, .rpm, snap).

Instalar a extensão Claude Code

No VS Code, abra o painel de extensões (Ctrl+Shift+X), busque por Claude Code (publicador: Anthropic) e clique em Install.

Abrir o terminal integrado e rodar o AIOX

bash — Terminal integrado (Ctrl+`)

claude  # inicia o Claude Code com acesso ao projeto aberto
# A extensão adiciona o painel lateral de Claude no editor

Cursor

Fork do VS Code com IA embutida — autocompletar avançado e chat contextual com seu código

Baixar o Cursor

Acesse cursor.com, clique em Download e siga o instalador para seu sistema operacional.

Importar configurações do VS Code (opcional)

Na primeira abertura, o Cursor oferece importar extensões e keybindings do VS Code automaticamente — aceite para manter sua configuração atual.

Adicionar regras AIOX no Cursor

O Cursor usa .cursor/rules/ em vez de CLAUDE.md. Copie o conteúdo para uma rule do Cursor:

bash

mkdir -p .cursor/rules
cp .claude/CLAUDE.md .cursor/rules/aiox.mdc

Sem lifecycle hooks: automações de PreToolUse e PostToolUse do AIOX não funcionam no Cursor. Para o fluxo completo de agentes, use o Claude Code na CLI.

Windsurf by Codeium

Editor com agente de IA "Cascade" embutido — experiência agentic sem CLI adicional

Baixar o Windsurf

Acesse codeium.com/windsurf e baixe o instalador para Windows, macOS ou Linux.

Criar conta Codeium (gratuito)

O Windsurf requer uma conta Codeium gratuita. Cadastre em codeium.com antes de abrir o editor.

Adicionar contexto AIOX via .windsurfrules

O Windsurf usa .windsurfrules na raiz do projeto para regras de contexto:

bash

# Gerar .windsurfrules com contexto AIOX
cp .claude/CLAUDE.md .windsurfrules

Cascade + AIOX: use o agente Cascade do Windsurf para geração de código e o Claude Code na CLI para executar o fluxo completo de agentes AIOX (stories, QA gates, releases).

Primeiro Uso

Definição de first-value: ativação + greeting + comando em ≤ 10 min

First-value (binário): Ativação de agente + greeting válido + comando inicial com output útil em menos de 10 minutos.

Abra seu CLI no projeto com AIOX instalado

bash

cd meu-projeto
claude  # ou: codex / gemini

Percebeu? Nenhum npx aqui. O AIOX já está instalado no projeto — basta abrir o CLI e ativar os agentes.

Ative um agente

bash

# No Claude Code:
@aiox-master

# No Gemini CLI:
/aiox-menu  # depois selecione o agente

# No Codex CLI:
/skills  # depois selecione aiox-<agent-id>

Confirme o greeting e rode o primeiro comando

bash

# Após o greeting do agente, teste:
*help  # lista todos os comandos disponíveis

Ativação por CLI

CLI	Paridade AIOX	Ativação de agente
Claude Code	🟢 Completa (referência)	@agent-name
Gemini CLI	🟡 Alta	/aiox-menu → /aiox-<agent>
Codex CLI	🟠 Parcial	/skills → aiox-<agent-id>
Cursor	🔴 Sem lifecycle hooks	Regras + MCP
AntiGravity	🔴 Workflow-based	Workflows (não hooks)
GitHub Copilot	🔴 Sem lifecycle hooks	Instruções de repositório + MCP

Agentes principais disponíveis

@aiox-master

Executor universal do AIOX. Use para qualquer tarefa que não requer persona específica.

@dev

Desenvolvedor full stack. Implementa stories com contexto arquitetural.

@architect

Arquiteto de sistemas. Cria PRDs, documentos de arquitetura e decisões técnicas.

@qa

Quality Assurance. Valida implementações e cria estratégias de teste.

@pm

Product Manager. Criação de PRDs e definição de features.

@sm

Scrum Master. Transforma PRDs em stories hiperdetalhadas para o @dev.

Troubleshooting

Problemas comuns e soluções

npx aiox-core não encontrado

Verifique se Node.js ≥ 18 está instalado: node --version. Se Node.js estiver instalado, tente npx aiox-core@latest init para buscar a versão mais recente.

Agente não responde ao @agent-name

Confirme que o AIOX foi instalado no projeto atual. O .aiox-core/ deve existir na raiz do projeto onde você abriu o Claude Code.

Erro de permissão no npm install global

bash

# Configure npm para instalar sem sudo
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Claude Code não reconhece AIOX após instalação

Feche e reabra o Claude Code na pasta do projeto. O AIOX é carregado quando o CLI é iniciado no diretório correto.

Preciso rodar npx toda vez que abrir o projeto?

Não. O npx é usado apenas para instalar ou atualizar o AIOX. No dia a dia, você abre o CLI (claude, codex ou gemini) dentro do projeto e usa os agentes diretamente com @agent-name. O framework já está instalado localmente na pasta .aiox-core/.

Problemas não listados aqui? Abra uma issue em github.com/SynkraAI/aiox-core/issues