Codex God Setup

Multi-agent orchestration system for OpenAI Codex CLI with 21 specialized agents, automated workflows, and cost-optimized model routing.

Quick Start

Option A: One-Command Install (Recommended)

npx codex-god-setup

That's it. All 21 agents, 15 reusable Codex skills, 9 hooks, and 3 pattern rules are installed globally and work in every project.

Note: Use npx, not npm install. This package is a CLI installer that sets up ~/.codex/ — it's not a library dependency.

Option B: Clone and Install

git clone https://github.com/iabhisekbosepm/codex-god-setup.git
cd codex-god-setup && ./setup.sh

What Gets Installed

~/.codex/
├── AGENTS.md          ← Global instructions (loaded every session)
├── config.toml        ← Model & feature configuration
├── hooks.json         ← Hook configuration
├── agents/            ← 21 agents
├── skills/            ← 15 reusable skills
├── patterns/          ← 3 shared rules
└── hooks/             ← 9 hook scripts

Safe to run multiple times (idempotent). Existing config files are backed up if non-empty.

Option C: Copy Into a Single Project

# Copy everything into your project
cp -r codex-god-setup/ your-project/.codex-god/

# Or just copy AGENTS.md to project root
cp codex-god-setup/AGENTS.md your-project/AGENTS.md

Codex CLI auto-reads AGENTS.md from the project root on every conversation start.

What Goes Where (Global vs Project)

| Resource | Global | Project | |----------|--------|---------| | Agents | ~/.codex/agents/*.md | .codex/agents/*.md | | Skills | ~/.codex/skills/*/SKILL.md | .agents/skills/*/SKILL.md | | Patterns | ~/.codex/patterns/*.md | patterns/*.md | | Hooks | ~/.codex/hooks.json + hooks/*.sh | .codex/hooks.json + .codex/hooks/*.sh | | Instructions | ~/.codex/AGENTS.md | AGENTS.md (project root) | | Config | ~/.codex/config.toml | .codex/config.toml |

Note: Project-level resources override globals with the same name.

How To Use It

This repo installs custom Codex skills, not built-in / menu commands.

• Type /skills to open the skills picker.
• Type $review, $plan, $audit, $quick-fix, etc. to invoke a skill directly.
• You can also describe the task normally, and Codex may choose a matching skill automatically based on the skill description.

Examples:

$review
$plan add Stripe subscription flow
$quick-fix login form submits twice
$security-audit src/api

Important:

• The plain / popup in Codex shows built-in slash commands such as /model, /status, and /agent.
• These custom repo skills do not appear there as /review or /plan.
• If you add or change skills and they do not appear yet, restart Codex.

Project Structure

codex-god-setup/
  setup.sh                  ← Global install script (run once)
  AGENTS.md                 ← AI instructions (loaded every session)
  README.md                 ← You are here (human docs)
  agents/                   ← 21 specialized agent definitions
  patterns/                 ← Shared coding standards & rules
  skills/
    skills.md               ← Skills routing matrix
  .agents/
    skills/                 ← 15 custom skill definitions
  .codex/
    hooks/                  ← 9 hook shell scripts

Agents (21)

| Agent | Purpose | Model | |-------|---------|-------| | architect | System design, scalability, trade-offs | gpt-5.4 | | planner | Implementation planning, phased delivery | gpt-5.4 | | code-architect | Feature blueprints from existing patterns | gpt-5.3-codex | | code-explorer | Deep codebase analysis, execution tracing | gpt-5.3-codex | | code-reviewer | General code quality, React/Node patterns | gpt-5.3-codex | | typescript-reviewer | TypeScript type safety, async, idiomatic TS/JS | gpt-5.3-codex | | python-reviewer | PEP 8, type hints, Pythonic idioms | gpt-5.3-codex | | security-reviewer | OWASP Top 10, secrets, auth, input validation | gpt-5.3-codex | | silent-failure-hunter | Empty catches, swallowed errors | gpt-5.3-codex | | comment-analyzer | Comment accuracy, staleness | gpt-5.3-codex | | build-error-resolver | Fix type/build errors with minimal diffs | gpt-5.3-codex | | performance-optimizer | Profiling, bundle, rendering, query optimization | gpt-5.3-codex | | code-simplifier | Simplify without changing behavior | gpt-5.3-codex | | refactor-cleaner | Dead code removal, duplicate consolidation | gpt-5.3-codex | | e2e-runner | E2E tests via Playwright | gpt-5.3-codex | | doc-updater | Codemaps, READMEs, API docs | gpt-5.4-mini | | seo-specialist | Technical SEO, meta tags, structured data | gpt-5.3-codex | | gan-planner | Expand prompt to full product spec | gpt-5.4 | | gan-generator | Build the app, iterate on feedback | gpt-5.4 | | gan-evaluator | Test live app, score, provide feedback | gpt-5.4 | | eval-architect | LLM eval pipeline: auto-detect, datasets, evaluators, CI | gpt-5.4 |

Skills (15)

| Skill | What It Does | Example | |-------|--------------|---------| | $review | Full code review pipeline | $review src/checkout | | $plan <feature> | Create implementation plan | $plan add team billing | | $pipeline <feature> | Full dev pipeline: explore to docs | $pipeline build invoice export | | $fix-build | Fix build/type errors | $fix-build | | $quick-fix <bug> | Diagnose, fix, verify a bug | $quick-fix file upload fails on Safari | | $audit | Run ALL quality gates | $audit | | $security-audit <path> | OWASP Top 10 + secrets scan | $security-audit src/api | | $explore <area> | Deep-dive codebase area | $explore auth flow | | $optimize <target> | Profile and fix performance | $optimize dashboard | | $cleanup | Remove dead code, simplify | $cleanup | | $docs | Update documentation | $docs | | $pr-review <number> | Review GitHub PR | $pr-review 42 | | $gan <prompt> | GAN harness from prompt | $gan build a habit tracker | | $seo-audit <url-or-path> | Technical SEO audit | $seo-audit https://example.com | | $eval [project] | Generate Langfuse evaluation pipeline | $eval support chatbot |

Hooks (9)

| Hook | Event | Effect | |------|-------|--------| | force-push-guard | PreToolUse | BLOCKS git push --force | | destructive-guard | PreToolUse | BLOCKS rm -rf /, git reset --hard | | git-push-guard | PreToolUse | WARNS on push to main/master | | pre-commit-check | PreToolUse | WARNS about secrets, console.log, TODOs | | env-setup | SessionStart | Loads environment, lists commands | | post-edit-track | PostToolUse | Tracks edited files for review | | stop-checklist | Stop | Reminds about pending reviews | | notify | Notification | macOS notification when input needed | | prompt-context | UserPromptSubmit | Extension point |

Automated Workflows

Build a Feature

code-explorer → architect → planner → build → build-error-resolver → code-reviewer → typescript/python-reviewer → security-reviewer → silent-failure-hunter → performance-optimizer → e2e-runner → doc-updater

Fix a Bug

code-explorer → fix → build-error-resolver → code-reviewer → security-reviewer → e2e-runner

Code Review (PR)

code-reviewer → typescript/python-reviewer → security-reviewer → silent-failure-hunter → comment-analyzer → performance-optimizer

Refactoring Sprint

code-explorer → refactor-cleaner → code-simplifier → build-error-resolver → code-reviewer → e2e-runner → doc-updater

GAN Harness

gan-planner → gan-generator → gan-evaluator → (iterate until 7.0/10) → code-reviewer → security-reviewer → doc-updater

SEO Audit

seo-specialist → performance-optimizer → fix → seo-specialist (verify)

Eval Pipeline

code-explorer (detect app type) → eval-architect (generate evals/) → verify → optionally setup_langfuse.py

Model Routing

| Tier | Model | Use For | |------|-------|---------| | Lite | gpt-5.4-mini | Docs, codemaps, formatting | | Standard | gpt-5.3-codex | Reviews, analysis, testing, refactoring | | Power | gpt-5.4 | Architecture, planning, GAN, creative judgment |

Extending This Setup

Add a New Agent

1. Create agents/your-agent.md with frontmatter:

   ---
   name: your-agent
   description: "What it does"
   tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
   model: gpt-5.3-codex
   ---

2. Write agent instructions in the body
3. Add to Skills Matrix in skills/skills.md

Add a New Skill

1. Create .agents/skills/your-command/SKILL.md:

   ---
   name: your-command
   description: "When to use this"
   argument-hint: "[argument]"
   allowed-tools: Read Write Edit Bash Grep Glob
   model: gpt-5.3-codex
   ---

2. Use $ARGUMENTS for user input
3. Reference agents/*.md for methodology
4. Invoke it with $your-command or from /skills

Add a New Hook

1. Create .codex/hooks/your-hook.sh (chmod +x)
2. Read JSON from stdin, write JSON to stdout
3. Exit 0 = continue, exit 2 = block
4. Register in .codex/hooks.json

Comparison: Claude God Setup vs Codex God Setup

| Aspect | Claude Version | Codex Version | |--------|---------------|---------------| | Instructions | CLAUDE.md | AGENTS.md | | Config dir | ~/.claude/ | ~/.codex/ | | Skills dir | ~/.claude/skills/ | ~/.codex/skills/ | | Hooks config | settings.json | hooks.json | | System config | Embedded in CLAUDE.md | config.toml | | Lite model | haiku | gpt-5.4-mini | | Standard model | sonnet | gpt-5.3-codex | | Power model | opus | gpt-5.4 | | CLI command | claude | codex | | Install | npx claude-god-setup | npx codex-god-setup |

Troubleshooting

| Problem | Solution | |---------|----------| | Skill not showing in /skills | Verify ~/.codex/skills/<name>/SKILL.md exists, then restart Codex | | Typed /review and nothing appeared | Use /skills or type $review directly; custom skills are not listed in the plain / popup | | Hook not firing | Check ~/.codex/hooks.json, verify codex_hooks = true in config.toml | | Hook blocking unexpectedly | Check exit code in hook script (2 = block) | | Agent not triggering | Reference agent file directly | | Wrong model | Check agent/skill frontmatter model field | | GAN stuck in loop | Check if score is improving, adjust spec | | Build agent over-changing | Tell it: "minimal diffs only" | | Config not loading | Check ~/.codex/config.toml syntax (must be valid TOML) |