Instalação AIOX (Mac) — Claude Code · Codex CLI

1

Requisitos do Sistema

Verifique antes de comecar

Requisito	Versao minima	Observacao
macOS	10.15+ (Catalina)	Catalina ou superior
Node.js	>= 18.0.0	v22 LTS recomendado — instale via NVM
npm	>= 9.0.0	Ja vem com o Node.js — ou use yarn / pnpm
RAM	4 GB+	8 GB recomendado

Claude Code tem instalador nativo Nao 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

Homebrew (Package Manager)

O gerenciador de pacotes do macOS

O que e o Homebrew?

The Missing Package Manager for macOS

O Homebrew e o equivalente do apt-get no Linux — permite instalar ferramentas de desenvolvimento (git, gh, node, etc.) com um unico comando no Terminal. E o padrao de facto para desenvolvimento no Mac.

1

Instalar o Homebrew

Abra o Terminal (Cmd+Espaco, digite "Terminal") e cole o comando abaixo:

bash — Terminal

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2

Verificar instalacao

bash

brew --version

Homebrew e opcional mas altamente recomendado. Simplifica a instalacao de ferramentas como git, gh (GitHub CLI), e muitas outras. Se preferir, pode instalar tudo manualmente — mas o Homebrew economiza muito tempo.

Apple Silicon (M1/M2/M3/M4): Apos instalar o Homebrew em Macs com Apple Silicon, pode ser necessario adicionar o path ao ~/.zshrc. O instalador mostra as instrucoes — siga o que aparecer no terminal.

3

Instalar Node.js

Necessario para AIOX Core, Codex CLI e Gemini CLI

🟢 Node.js

E o motor de execucao do JavaScript fora do navegador. Pense nele como o "motor de um carro" — e o que faz o JavaScript rodar na sua maquina.

📦 npm (Node Package Manager)

E o gerenciador de pacotes que vem junto com o Node.js. E como a "loja de pecas" do carro — voce usa para instalar bibliotecas e ferramentas.

Instalar via NVM (recomendado)

bash — Terminal macOS

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
npm -v

Por que NVM? O NVM instala o Node.js no espaco do usuario — sem sudo, sem conflito de versoes. O --lts sempre pega a versao LTS mais estavel disponivel.

O que e CLI?

Command Line Interface — Interface de Linha de Comando

E quando voce controla um programa digitando comandos de texto no terminal, em vez de clicar em botoes numa tela.

	Interface Visual (GUI)	CLI
O que e	Janelas, botoes, icones	Texto puro no terminal
Exemplo	Abrir o VS Code clicando	code . no terminal
Quem usa	Qualquer pessoa	Desenvolvedores

Analogia simples:
GUI e como dirigir um carro automatico — intuitivo, visual.
CLI e como pilotar com cambio manual — mais controle, mais velocidade, curva de aprendizado maior.

Ferramentas CLI essenciais

Alem do Node.js, o AIOX usa o GitHub CLI (para PRs, CodeRabbit e controle de versao) e o Vercel CLI (para deploy de paginas e projetos). Instale ambos antes de continuar.

GitHub CLI gh

Gerencia repositorios, PRs e issues direto no terminal — necessario para CodeRabbit e @devops

bash — macOS (Homebrew)

brew install gh

Autenticar no GitHub

bash — login (abre o browser)

gh auth login
# Escolha: GitHub.com -> HTTPS -> Login with a web browser
# Copie o codigo, cole no browser e autorize

# Verificar autenticacao:
gh auth status

Vercel CLI

Deploy de paginas e projetos, gerenciamento de dominios e variaveis de ambiente

bash — instalar globalmente

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

Autenticar na Vercel

bash — login (abre o browser)

vercel login
# Abre o browser — faca login com GitHub, GitLab ou email

# Verificar autenticacao:
vercel whoami

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

Verificacao rapida: apos instalar tudo, confirme que os 3 CLIs estao disponiveis:

bash — verificar instalacao

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

4

Claude Code

CLI oficial da Anthropic — melhor compatibilidade com AIOX

Claude Code tem paridade de hooks completa com o AIOX E o CLI de referencia para automacao maxima de contexto, guardrails e auditoria. Se voce vai usar apenas um CLI, use Claude Code.

bash — Terminal macOS

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

# Verificar instalacao
claude --version

# Iniciar (vai pedir login Anthropic)
claude

Apos instalar, abra claude no terminal. Ele vai abrir o processo de autenticacao com a Anthropic. Voce precisa de uma conta em claude.ai.

Sync dedicado de agentes: O arquivo .claude/CLAUDE.md e carregado automaticamente. Para sincronizar agentes com o Claude Code apos 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, tambem disponivel 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 automacoes dependem do AGENTS.md, /skills e MCP. Ativacao 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 ja inclui acesso ao Gemini 2.5 Pro com janela de 1M tokens.

Plano	Limites no Gemini CLI	Preco
Conta Google (gratis)	60 req/min . 1.000 req/dia	Gratis
Google AI Pro	Limites maiores (ideal para uso diario)	~US$ 19,99/mes
Google AI Ultra	Limites mais altos + prioridade	~US$ 249,99/mes

Gemini CLI tem alta paridade de hooks com AIOX. Ativacao de agentes usa /aiox-menu -> /aiox-<agent>. Boa cobertura de automacoes pre/post tool e sessao.

7

Repositorios Synkra AIOX

O ecossistema open source do AIOX

Organizacao SynkraAI no GitHub Todos os repositorios AIOX sao open source e estao em github.com/SynkraAI.

aiox-core

SynkraAI / aiox-core

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

Obrigatorio npm package v5.0.3 2.1k

mcp-ecosystem

SynkraAI / mcp-ecosystem

Configuracoes MCP prontas. Presets para desenvolvimento, pesquisa e full. Configs para Claude Code e Cursor.

Opcional configs

SynkraAI

github.com / SynkraAI

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

Organizacao

8

Instalar AIOX Core Principal

Um comando instala tudo — voce so roda npx uma vez

npx e so na instalacao. Voce roda npx aiox-core init apenas uma vez para criar o projeto. Depois disso, o AIOX ja esta instalado localmente e voce usa os agentes direto na IDE (Claude Code, Cursor, etc.) sem precisar rodar npx novamente. Pense no npx como o instalador de um programa — voce usa uma vez e depois abre o programa normalmente.

bash

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

# Ou com versao especifica
npx aiox-core@latest init meu-projeto

bash

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

# O instalador detecta automaticamente sua configuracao

bash

# Upstream Auto-Update — atualiza sem perder customizacoes
npx aiox-core@latest install

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

# Verificar saude apos atualizar
npx aiox-core doctor

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

O que o updater faz automaticamente: detecta a instalacao existente, faz backup das suas customizacoes em .aiox-backup/, atualiza apenas os arquivos do core que mudaram e preserva suas configuracoes, squads e templates personalizados.

O que o instalador faz

Download da versao mais recente do NPM

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

Configuracao automatica do IDE (Codex CLI, Cursor ou Claude Code)

Setup de todos os agentes e workflows AIOX no projeto

Criacao dos arquivos de configuracao necessarios

Inicializacao do sistema de meta-agentes

Verificacoes de saude do sistema

Suporte nativo a macOS (Intel e Apple Silicon)

Estrutura instalada

estrutura

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

Verificar instalacao

Apos instalar, confirme que tudo esta funcionando:

bash

npx aiox-core doctor

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

saida esperada

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

9

MCP Ecosystem

Servidores MCP que ampliam as capacidades do Claude Code

MCPs opcionais do AIOX

Os MCPs nao estao incluidos no npx aiox-core install. Sao 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	Nao	Documentacao atualizada de bibliotecas para LLMs	@dev
desktop-commander	Nao	Gerenciamento de arquivos e comandos de terminal	@dev
playwright	Nao	Automacao de browser para testes	@qa
exa	Sim (free tier)	Busca web com IA e extracao de conteudo	@analyst
github	Sim (PAT)	Gerencia repositorios, issues, PRs e branches via prompt	@devops
vercel	Sim (OAuth)	Gerencia deployments, logs, projetos e dominios via prompt	@devops

Recomendacao para iniciantes: instale apenas context7 e desktop-commander (sem chave API, zero configuracao extra). Os demais sao para uso avancado.

Escopos do MCP (Claude Code)

O Claude Code usa um sistema de escopos para saber onde salvar cada configuracao de MCP. Entender isso evita confusao na hora de instalar. Gemini CLI e Codex CLI tem seus proprios formatos — veja as abas de instalacao abaixo.

Estrutura de pastas no seu ambiente

estrutura

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

Os dois escopos principais

Escopo	Flag	Arquivo	Disponivel em
user (global)	--scope user	~/.claude.json	Todos os projetos
project	--scope project	.mcp.json na raiz do projeto	So 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 esta no global fica disponivel automaticamente — sem nenhuma configuracao extra no projeto.

Como instalar os MCPs

Cada CLI tem seu proprio sistema de configuracao de MCPs. Os comandos de instalacao nao sao intercambiaveis entre Claude Code, Gemini CLI e Codex CLI. Escolha a aba correspondente ao CLI que voce esta usando.

Usa claude mcp add --scope user -> salva em ~/.claude.json. Disponivel globalmente em qualquer projeto:

bash — Claude Code

# context7 — documentacao 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 — automacao 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 disponivel)

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

# Passo 2: ativar
source ~/.zshrc

# 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/mes). A chave fica salva no .zshrc localmente — nunca e exposta no chat ou commitada no repositorio.

Vercel MCP — MCP remoto (OAuth)

O Vercel MCP usa OAuth — nao precisa gerar token manualmente. O login e feito uma unica vez pelo browser usando sua conta Vercel.

bash — Vercel MCP (Claude Code)

# vercel — gerenciamento de deployments, logs e projetos (requer autenticacao OAuth)

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

# Passo 2: abrir uma sessao do Claude Code
claude

# Passo 3: autenticar com sua conta Vercel
/mcp
# Vai abrir o browser — faca login com sua conta Vercel e autorize o acesso
# Apos autorizar, feche o browser e volte ao terminal

Com o Vercel MCP configurado voce consegue via prompt: ver status de deployments, analisar logs de erro, gerenciar projetos e dominios.

Teste rapido: abra uma sessao com claude e peca: "Liste meus projetos na Vercel". Se retornar os dados, esta configurado corretamente.

GitHub MCP — MCP remoto

Diferente dos outros MCPs, o GitHub MCP e 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 repositorios, issues e PRs (requer Personal Access Token)

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

# Passo 2: ativar
source ~/.zshrc

# 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 permissoes: repo, read:org e workflow. O token fica salvo localmente — nunca e exposto no chat ou commitado no repositorio.

Nota tecnica: o GitHub MCP e 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 nao deve ser usado.

Teste rapido: abra uma sessao do Claude Code com claude e peca: "Liste meus repositorios do GitHub". Se retornar a lista dos seus repos, esta configurado corretamente. Se der erro de autenticacao, o token esta errado ou expirado.

Verificar MCPs instalados

bash

claude mcp list              # listar todos os MCPs
claude mcp get context7     # detalhes de um MCP especifico
claude mcp get github       # verificar configuracao do GitHub MCP
claude mcp get vercel       # verificar configuracao do Vercel MCP

O Gemini CLI usa um arquivo de configuracao proprio (settings.json) e nao tem comando mcp add — voce 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 diretorio se nao existir: mkdir -p ~/.gemini e depois crie o arquivo settings.json com o conteudo acima.

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

bash — Codex CLI

# context7 — documentacao 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 — automacao 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 variaveis de ambiente no .zshrc (como nos exemplos de Exa e GitHub acima). As chaves ficam salvas localmente — nunca sao expostas no chat ou commitadas no repositorio.

Consumo de tokens e contexto

Cada MCP carregado injeta as definicoes dos seus tools no contexto da sessao — isso consome tokens. Quanto mais MCPs ativos, mais contexto ocupado antes mesmo de voce digitar qualquer coisa.

Tool Search — otimizacao automatica

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%

reducao automatica

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

Conclusao pratica: instale os MCPs que voce realmente usa. O Tool Search cuida do resto.

10

CodeRabbit — Plugin de Code Review Destaque

Plugin de revisao automatica de codigo com IA — integrado ao Claude Code

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

O que e um PR (Pull Request)? E uma solicitacao para incluir suas alteracoes de codigo no repositorio principal do projeto. Funciona assim: voce trabalha numa copia separada (branch), e quando termina, abre um PR pedindo que as mudancas sejam revisadas e aprovadas antes de entrar no codigo principal. E onde o time (ou o CodeRabbit) revisa a qualidade do codigo.

Integrado na camada 2 dos Quality Gates do framework AIOX

O CodeRabbit esta 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): revisao de arquitetura, aprovacao final

Pre-requisito: o projeto precisa ser um repositorio Git (git init ou git clone). CodeRabbit nao funciona fora de repositorios Git.

Duas formas complementares de uso

1. GitHub App (automatico 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 so entrega quando o review estiver limpo.

Pre-requisito — dependencias do sistema

No Mac, as dependencias basicas ja estao disponiveis. O curl e o git vem com o Xcode Command Line Tools. Se nao tiver instalado ainda:

bash — instalar Xcode Command Line Tools

xcode-select --install  # instala Xcode Command Line Tools se nao tiver

Instalacao — passos comuns (todas as CLIs)

Cada CLI tem sua propria forma de integrar o CodeRabbit. Os passos 1 e 2 (instalar CLI + autenticar) sao iguais para todos. O passo 3 (integracao com a CLI de IA) muda conforme o tool que voce usa.

1

Instalar o CLI do CodeRabbit (todas as CLIs)

bash

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

2

Autenticar (todas as CLIs)

bash

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

3

Conectar ao repositorio GitHub (todas as CLIs)

Acesse https://coderabbit.ai -> login com GitHub -> autorize o repositorio. A partir dai, todo PR recebe review automatico.

Integracao 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 e 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 disponiveis apos instalacao

bash — slash commands

/coderabbit:review               # revisa todas as mudancas
/coderabbit:review uncommitted   # so mudancas nao commitadas
/coderabbit:review committed     # so mudancas commitadas
/coderabbit:review --base main   # compara com main

O Gemini CLI nao tem sistema de plugins. O CodeRabbit e usado como ferramenta CLI independente — voce roda os comandos diretamente no terminal:

bash — uso direto do CLI

# Revisar mudancas nao commitadas
coderabbit review --uncommitted

# Revisar mudancas commitadas
coderabbit review --committed

# Comparar com branch main
coderabbit review --base main

Dica: voce 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 tambem nao tem sistema de plugins. Use o CodeRabbit como CLI independente no terminal:

bash — uso direto do CLI

# Revisar mudancas nao commitadas
coderabbit review --uncommitted

# Revisar mudancas commitadas
coderabbit review --committed

# Comparar com branch main
coderabbit review --base main

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

Plano gratuito: o plugin funciona completamente no tier gratuito. Repositorios open source tem CodeRabbit sempre gratuito.

11

IDE Editores de Codigo Opcional

Configure seu editor com IA — compatibilidade e passo a passo de instalacao

O que e uma IDE?

Integrated Development Environment — Ambiente de Desenvolvimento Integrado

E um programa que reune tudo que um desenvolvedor precisa em um so lugar: editor de texto, terminal, debug, controle de versao (Git) e — nos IDEs modernos — IA integrada.

Como IDE e CLI se complementam no AIOX:
Voce usa a IDE para visualizar e editar o codigo — e o Claude Code na CLI (terminal integrado da propria IDE) para orquestrar agentes, rodar stories e fazer deploys.
O fluxo e: IDE aberta -> terminal integrado -> claude -> agentes AIOX em acao.

No Mac, todos os editores rodam nativamente. Basta baixar, instalar e abrir. O terminal integrado de cada editor ja usa o shell padrao do macOS (zsh).

O AIOX roda no terminal, nao no editor. Editores com IA funcionam como complemento — a execucao de agentes, stories e workflows acontece sempre na CLI. Use o editor para edicao e a CLI para orquestracao.

AntiGravity by Google Recomendado pelo AIOX

IDE agentica do Google — 16 agentes especializados, MCP Store integrada e suporte a multiplos modelos (Gemini, Claude, GPT). Gratuita na preview publica.

1

Baixar e instalar o AntiGravity

Acesse antigravity.google/download e execute o instalador. Disponivel para macOS (Intel e Apple Silicon). Autenticacao com conta Google.

2

Configurar MCP no AntiGravity

O AntiGravity tem sua propria configuracao 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
Tambem possui uma MCP Store integrada para buscar e instalar servidores diretamente.

3

Verificar o AGENTS.md no projeto

O AntiGravity le o AGENTS.md e o GEMINI.md na raiz do projeto — ambos ja gerados pelo AIOX.

VS Code

O editor mais popular — suporte ao AIOX via extensao Claude Code oficial da Anthropic

1

Baixar o VS Code

Acesse code.visualstudio.com e baixe a versao para macOS (Universal ou Apple Silicon).

2

Instalar a extensao Claude Code

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

3

Abrir o terminal integrado e rodar o AIOX

bash — Terminal integrado (Ctrl+` ou Cmd+`)

claude  # inicia o Claude Code com acesso ao projeto aberto

Cursor

Fork do VS Code com IA embutida — autocompletar avancado e chat contextual com seu codigo

1

Baixar o Cursor

Acesse cursor.com, clique em Download e arraste para a pasta Applications.

2

Adicionar regras AIOX no Cursor

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

bash

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

Windsurf by Codeium

Editor com agente de IA "Cascade" embutido — experiencia agentic sem CLI adicional

1

Baixar o Windsurf

Acesse codeium.com/windsurf e baixe o instalador para macOS.

2

Adicionar contexto AIOX via .windsurfrules

bash

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

12

Primeiro Uso

Definicao de first-value: ativacao + greeting + comando em <= 10 min

First-value (binario): Ativacao de agente + greeting valido + comando inicial com output util 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 ja esta 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

# Apos o greeting do agente, teste:
*help  # lista todos os comandos disponiveis

Ativacao por CLI

CLI	Paridade AIOX	Ativacao de agente
Claude Code	Completa (referencia)	@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 (nao hooks)
GitHub Copilot	Sem lifecycle hooks	Instrucoes de repositorio + MCP

Agentes principais disponiveis

@aiox-master

Executor universal do AIOX. Use para qualquer tarefa que nao requer persona especifica.

@dev

Desenvolvedor full stack. Implementa stories com contexto arquitetural.

@architect

Arquiteto de sistemas. Cria PRDs, documentos de arquitetura e decisoes tecnicas.

@qa

Quality Assurance. Valida implementacoes e cria estrategias de teste.

@pm

Product Manager. Criacao de PRDs e definicao de features.

@sm

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

Troubleshooting

Problemas comuns no macOS e solucoes

Erro de permissao 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' >> ~/.zshrc
source ~/.zshrc

Xcode Command Line Tools nao instalado

Se ao rodar git ou curl aparecer erro sobre ferramentas de desenvolvimento ausentes, rode:

bash

xcode-select --install

npx aiox-core nao encontrado

Verifique se Node.js >= 18 esta instalado: node --version. Se Node.js estiver instalado, tente npx aiox-core@latest init para buscar a versao mais recente.

Agente nao responde ao @agent-name

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

Claude Code nao reconhece AIOX apos instalacao

Feche e reabra o Claude Code na pasta do projeto. O AIOX e carregado quando o CLI e iniciado no diretorio correto.

Homebrew nao encontrado apos instalacao (Apple Silicon)

Em Macs com Apple Silicon (M1/M2/M3/M4), o Homebrew instala em /opt/homebrew. Adicione ao PATH:

bash

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

Preciso rodar npx toda vez que abrir o projeto?

Nao. O npx e usado apenas para instalar ou atualizar o AIOX. No dia a dia, voce abre o CLI (claude, codex ou gemini) dentro do projeto e usa os agentes diretamente com @agent-name. O framework ja esta instalado localmente na pasta .aiox-core/.

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

Instale o AIOX

Requisitos do Sistema

Homebrew (Package Manager)

Instalar Node.js

Instalar via NVM (recomendado)

Ferramentas CLI essenciais

Autenticar no GitHub

Autenticar na Vercel

Claude Code

Codex CLI Opcional

Gemini CLI Opcional

Repositorios Synkra AIOX

Instalar AIOX Core Principal

O que o instalador faz

Estrutura instalada

Verificar instalacao

MCP Ecosystem

MCPs opcionais do AIOX

Escopos do MCP (Claude Code)

Como instalar os MCPs

Vercel MCP — MCP remoto (OAuth)

GitHub MCP — MCP remoto

Verificar MCPs instalados

Consumo de tokens e contexto

CodeRabbit — Plugin de Code Review Destaque

Pre-requisito — dependencias do sistema

Instalacao — passos comuns (todas as CLIs)

Integracao por CLI

Comandos disponiveis apos instalacao

IDE Editores de Codigo Opcional

AntiGravity by Google Recomendado pelo AIOX

VS Code

Cursor

Windsurf by Codeium

Primeiro Uso

Ativacao por CLI

Agentes principais disponiveis

Troubleshooting