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)