Instalação AIOX — Claude Code · Codex CLI

1

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.

2

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.

1

Abra o PowerShell como Administrador

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

2

Instale o WSL com Ubuntu

powershell

wsl --install -d Ubuntu

3

Reinicie o computador

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

4

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.

3

Instalar Node.js

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

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.

4

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

5

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.

6

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.

7

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

aios-dashboard

SynkraAI / aios-dashboard

Interface web de observabilidade. Kanban de stories, monitor de eventos em tempo real, visualização de agentes e squads.

Opcional Dev inicial

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, aios-dashboard e mcp-ecosystem.

Organização

8

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.

9

AIOS Dashboard Opcional

Interface web de observabilidade — precisa de AIOX Core instalado

Em desenvolvimento ativo. O repositório permanece como aios-dashboard e os comandos de instalação do dashboard continuam usando aios-core. Contribuições são bem-vindas!

O AIOX funciona 100% sem o Dashboard. Ele existe apenas para observar o que acontece na CLI — nunca para controlar. A CLI é sempre a fonte da verdade.

Instalar o Dashboard

bash

# Dentro do projeto com AIOX instalado
mkdir -p apps
git clone https://github.com/SynkraAI/aios-dashboard.git apps/dashboard

# Dependências do Dashboard (Next.js)
npm install --prefix apps/dashboard

# Dependências do Server (requer Bun — https://bun.sh)
cd apps/dashboard/server
bun install

Iniciar (2 terminais)

bash — Terminal 1: Server de eventos (porta 4001)

cd apps/dashboard/server
bun run dev
# Saída esperada: 🚀 Monitor Server running on http://localhost:4001

bash — Terminal 2: UI do Dashboard (porta 3000)

npm run dev --prefix apps/dashboard
# Saída esperada: ▲ Next.js — Local: http://localhost:3000

Requer Bun. O server do Dashboard usa Bun como runtime. Instale em bun.sh antes de rodar o server. O Dashboard em si (Next.js) usa npm normalmente.

Abra http://localhost:3000 no navegador.

Views disponíveis

View	O que faz
Kanban	Board de stories com drag-and-drop (Backlog, Doing, Done)
Monitor	Feed em tempo real de eventos do Claude Code (tools, prompts, erros)
Agents	Lista de agentes AIOX ativos e em standby
Squads	Organograma visual dos squads instalados
Insights	Estatísticas e métricas do projeto

10

MCP Ecosystem e CodeRabbit Opcional

Ferramentas que ampliam as capacidades do AIOX

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
context7	❌ Não	Documentação atualizada de bibliotecas para LLMs
desktop-commander	❌ Não	Gerenciamento de arquivos e comandos de terminal
playwright	❌ Não	Automação de browser para testes
exa	✅ Sim	Busca web com IA e extração de conteúdo

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.

Como instalar

bash

# Clonar o ecossistema MCP
git clone https://github.com/SynkraAI/mcp-ecosystem.git
cd mcp-ecosystem

# Ver os presets disponíveis
ls presets/

Copie os blocos de mcpServers do preset escolhido para ~/.claude.json.

Preset	MCPs incluídos	Uso ideal
aios-dev.json	context7, desktop-commander, playwright	Implementação de stories
aios-research.json	context7, exa, playwright	Pesquisa, documentação
aios-full.json	Todos	Tarefas complexas multi-domínio

Não substitua o arquivo inteiro — mescle apenas os blocos mcpServers do preset com os que você já tem configurados em ~/.claude.json.

CodeRabbit — Code Review com IA Destaque

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.

Instalação — 4 passos

1

Instalar o CLI

bash

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

2

Autenticar (uma vez por sessão)

bash

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

3

Instalar o Plugin no Claude Code

bash

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

4

Conectar ao repositório GitHub (uma vez só)

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

Comandos do Plugin dentro do Claude Code

bash

/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 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.

11

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.

1

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.

2

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>

3

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/.

Dashboard não inicia / erro no server

O server do Dashboard requer Bun como runtime. Verifique:

bash

# Verificar se Bun está instalado
bun --version

# Se não estiver, instale:
curl -fsSL https://bun.sh/install | bash

# Reinicie o terminal e tente novamente
cd apps/dashboard/server
bun install
bun run dev

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

Instale o AIOX

Requisitos do Sistema

WSL no Windows

Instalar Node.js

Claude Code

Codex CLI Opcional

Gemini CLI Opcional

Repositórios Synkra AIOX

Instalar AIOX Core Principal

O que o instalador faz

Estrutura instalada

Verificar instalação

AIOS Dashboard Opcional

Instalar o Dashboard

Iniciar (2 terminais)

Views disponíveis

MCP Ecosystem e CodeRabbit Opcional

MCPs opcionais do AIOX

Como instalar

CodeRabbit — Code Review com IA Destaque

Instalação — 4 passos

Comandos do Plugin dentro do Claude Code

O loop autônomo com AIOX

Primeiro Uso

Ativação por CLI

Agentes principais disponíveis

Troubleshooting