MÓDULO 3.1

📦 Instalação Passo a Passo

Do zero ao primeiro /claudex plan rodando. Pré-requisitos, instalação, primeira configuração e troubleshooting comum.

1

📋 Pré-requisitos

Antes de começar, você precisa de 3 coisas instaladas e configuradas:

1. Claude Code (CLI)

A ferramenta de linha de comando da Anthropic. Versão 1.0+ recomendada.

npm install -g @anthropic-ai/claude-code
claude --version  # confirma versão

2. Codex CLI (OpenAI)

O segundo modelo no ciclo. Você precisa de ChatGPT Plus ou conta OpenAI com acesso ao Codex.

npm install -g @openai/codex
codex --version

3. Bash + utilitários básicos

macOS e Linux já têm. No Windows, use WSL2 ou Git Bash.

2

🔍 Verificação do ambiente

Antes de instalar o plugin, valide que tudo funciona:

# Claude Code está logado?
claude auth status

# Codex está logado?
codex auth status

# Versões corretas?
claude --version  # >= 1.0.0
codex --version   # >= 0.5.0

Se algum comando falhou, resolva antes de prosseguir. Plugin não vai funcionar com ambiente quebrado.

3

📥 Instalação do plugin

No diretório do seu projeto:

# Entrar no projeto
cd meu-projeto

# Instalar plugin via Claude Code
claude plugin add iclaudex

# Verificar instalação
ls .claude/claudex/  # deve mostrar hooks/, commands/, etc

O plugin é instalado por projeto. Cada projeto tem seu próprio .claude/claudex/. Isso é proposital — projetos diferentes podem ter configurações diferentes.

4

⚙️ Primeira configuração

Após instalar, configure o número padrão de rodadas (opcional):

# .claude/claudex/config.yaml (opcional)
default_rounds: 3
default_personas:
  - engineer
  - security
  - ops

Se você não criar esse arquivo, o plugin usa os padrões — 3 rodadas com engineer/security/ops. 90% dos casos isso é suficiente.

5

🩺 /claudex:doctor — diagnóstico

Antes de rodar seu primeiro plano, valide tudo com o comando de diagnóstico:

$ /claudex:doctor

🩺 iClaudex Doctor
═══════════════════════════════════════
✅ Claude Code: 1.2.3
✅ Codex CLI:   0.7.1
✅ Bash:        5.1
✅ Plugin:      .claude/claudex/ instalado
✅ Hook:        registrado em settings.json
✅ Permissões:  hooks executáveis
✅ Auth:        Claude OK · Codex OK

Status: PRONTO PARA USO

Se algum item aparecer com ✗, o doctor explica como resolver. Sempre rode /claudex:doctor antes da primeira execução em um projeto novo.

6

🔧 Troubleshooting comum

❌ "codex: command not found"

Causa: Codex CLI não instalado ou fora do PATH.

Fix: npm install -g @openai/codex

❌ "Permission denied: stop.sh"

Causa: hook não tem permissão de execução.

Fix: chmod +x .claude/claudex/hooks/*.sh

❌ "Hook não dispara"

Causa: hook não registrado em settings.json.

Fix: claude plugin reinstall iclaudex

❌ "Lockfile fantasma"

Causa: ciclo anterior abandonado.

Fix: /claudex:rollback ou aguardar 15min (varredor automático).

💡 Dica

Se nada acima funcionou, rode /claudex:doctor --verbose para diagnóstico detalhado. Ele lista todos os checks individualmente, com mensagens completas de erro.

📌 Resumo

✓
3 pré-requisitos — Claude Code, Codex CLI, Bash.
✓
Verifique o ambiente antes — auth status nos dois.
✓
Plugin é por projeto — instala em .claude/claudex/.
✓
Configuração é opcional — padrões cobrem 90% dos casos.
✓
Sempre rode /claudex:doctor — antes da primeira execução.
✓
4 erros mais comuns — codex faltando, permissão, hook não registrado, lockfile.

Próximo Módulo:

3.2 — ▶️ O comando /claudex plan

← Voltar à TrilhaPróximo →