ccsetup

One-command setup for Claude Code and Codex projects. Creates a ready-to-use project structure with planning tools, review workflows, and optional AI-specific project setup.

Quick Start

# Interactive mode
npx ccsetup

# Create new project
npx ccsetup my-project

# Setup in current directory
npx ccsetup .

What You Get

my-project/
├── CLAUDE.md              # Project instructions for Claude (Claude/Both)
├── AGENTS.md              # Project instructions for Codex (Codex/Both)
├── CONTRIBUTING.md        # Contribution guidelines
├── GEMINI.md              # Gemini setup (optional)
├── .claude/
│   ├── agents/            # 8 core agents
│   ├── skills/            # /prd, /ralph, /codex-review, and /secops skills
│   └── settings.json      # Claude permissions and optional hook wiring
├── .codex/
│   ├── README.md          # Codex directory notes
│   └── skills/            # Project-local Codex skills: prd, ralph, claude-review, secops
├── agents/
│   └── README.md          # Agent documentation
├── scripts/
│   ├── ralph/             # Autonomous agent loop for Claude Code or Codex
│   ├── claude-review/     # Claude Code review script
│   └── codex-review/      # Codex CLI review script
├── docs/
│   ├── ROADMAP.md         # Development roadmap
│   └── agent-orchestration.md
├── tickets/               # Task tracking
└── plans/                 # Planning documents

Core Agents

backend, blockchain, checker, coder, frontend, planner, researcher, shadcn

Skills (Slash Commands)

• /prd — Scans your codebase (tech stack, quality gates, architecture), then generates a structured PRD with real file paths and auto-detected quality criteria
• /ralph — Converts a PRD into prd.json format for autonomous execution, with exact quality check commands and file hints per story
• /codex-review — Claude-facing cross-model review skill that reviews plans, validates implementations against plans, or reviews code changes via Codex CLI
• /claude-review — Codex-facing cross-model review skill that reviews plans, validates implementations against plans, or reviews code changes via Claude Code
• /secops — Security skill that blocks dependency installs until osv-scanner checks the package or lockfile for known vulnerabilities

Claude projects also ship with osv-scanner Bash permissions preconfigured in .claude/settings.json so the /secops workflow can run without extra permission prompts. Codex projects get the same workflow guidance in .codex/skills/secops/SKILL.md, but without Claude-specific hook or permission wiring.

Key Options

npx ccsetup my-project --agents        # Interactive agent selection
npx ccsetup my-project --all-agents    # Include all agents
npx ccsetup my-project --no-agents     # Skip agent selection entirely
npx ccsetup my-project --dry-run       # Preview without creating files
npx ccsetup my-project --force         # Skip prompts, overwrite existing
npx ccsetup my-project --browse        # Enhanced template browsing UI
npx ccsetup --install-hooks            # Install workflow selection hooks (advanced)

During setup, ccsetup asks whether to generate a Claude, Codex, or Both project environment.

Agent Workflows

Pre-configured multi-agent workflows:

• Feature Development: Researcher → Planner → Coder → Checker
• Bug Fix: Researcher → Coder → Checker
• API Development: Planner → Backend → Frontend → Checker
• UI Components: Frontend → Shadcn → Checker

See docs/agent-orchestration.md for details.

Workflow Selector Hook (Optional)

An optional hook that analyzes your prompts and suggests the best agent workflow for the task. Claude will ask before applying the suggestion.

During setup, you'll be asked if you want to install it. You can also install it later:

npx ccsetup --install-hooks

To activate, set the environment variable:

export CCSETUP_WORKFLOW=1

When active, the hook suggests workflows like "Feature Development: Researcher → Planner → Coder → Checker" and asks if you'd like to follow it. When the env var is unset, the hook exits silently and Claude uses its default behavior.

Codex Review — Plan, Implementation, and Code Review

Get a second opinion from OpenAI's Codex CLI. The script auto-detects what to review:

Context	Review Mode
Plan file, no code changes	Plan review — architectural soundness
Plan file + git changes	Implementation review — validates code against the plan
No plan file, git changes	Code review — bugs, security, quality

Usage

/codex-review                              # Auto-detect from context
/codex-review plans/my-feature-plan.md     # Review a specific plan

What happens

1. Detects available context (plan file and/or git changes)
2. Sends to Codex CLI with a mode-appropriate review prompt
3. Presents structured feedback (architecture, compliance, risks, suggestions)
4. Asks if you want to apply fixes and re-review
5. Repeats for up to 3 iterations

Direct script usage

# Plan review (no git changes)
./scripts/codex-review/codex-review.sh plans/my-plan.md

# Implementation review (plan + git changes auto-detected)
./scripts/codex-review/codex-review.sh plans/my-plan.md

# Code review (no plan, just git changes)
./scripts/codex-review/codex-review.sh

# Override the model
./scripts/codex-review/codex-review.sh plans/my-plan.md --model o3-mini

# From stdin
cat plans/my-plan.md | ./scripts/codex-review/codex-review.sh -

Prerequisites

1. Codex CLI installed: npm install -g @openai/codex
2. Authenticated: codex login or set OPENAI_API_KEY

Codex Review Hook (Optional)

An optional hook that suggests running /codex-review when plan files or scripts/ralph/prd.json are modified, or when code changes are detected. Triggers on the Stop event.

To activate:

export CCSETUP_CODEX_REVIEW=1

When unset, the hook is inactive and produces no output.

Ralph — Autonomous Agent Loop

Ralph is an autonomous coding agent that implements user stories from a PRD one at a time, with built-in subagent verification.

Workflow

1. Create a PRD — Use /prd in Claude Code to generate a codebase-aware PRD
2. Convert to Ralph format — Use /ralph to generate scripts/ralph/prd.json with quality checks and file hints
3. Run Ralph — Launch the autonomous loop:

# Default: 10 iterations using Claude Code
./scripts/ralph/ralph.sh

# Use Claude Code explicitly
./scripts/ralph/ralph.sh --tool claude

# Use Codex CLI instead of Claude Code
./scripts/ralph/ralph.sh --tool codex

# Specify model and max iterations
./scripts/ralph/ralph.sh --tool claude --model opus 20

# Quick Codex run
./scripts/ralph/ralph.sh --tool codex --model gpt-5 5

Codex mode uses scripts/ralph/CODEX.md, reads scripts/ralph/prd.json, and appends progress to scripts/ralph/progress.txt.

What happens each iteration

1. Reads prd.json and picks the next incomplete story
2. Reads story notes for file hints (pre-populated by /ralph)
3. Implements the story
4. Runs exact quality check commands from prd.json (qualityChecks field)
5. Spawns a checker subagent to independently verify the implementation against acceptance criteria
6. If reviewer approves → commits. If not → fixes and re-verifies (up to 3 cycles)
7. Updates prd.json (passes: true) and appends to progress.txt
8. Exits when all stories pass, or after max iterations

Options

Flag	Default	Description
--tool claude|codex	claude	Which AI tool to use
--model <model>	(default)	Model selection for the chosen tool
[number]	10	Max iterations

Archiving

Ralph auto-archives previous runs when the branch changes. Archives are saved to scripts/ralph/archive/YYYY-MM-DD-feature-name/.

Prerequisites

1. jq installed for PRD parsing and branch tracking
2. Claude Code CLI for the default runner
3. Codex CLI if you want --tool codex: npm install -g @openai/codex

Typical Codex workflow:

1. Run /prd
2. Run /ralph
3. Run ./scripts/ralph/ralph.sh --tool codex
4. Run ./scripts/claude-review/claude-review.sh for a cross-model review when needed

Documentation

• Agent Orchestration
• Available Agents
• Codex Setup
• Ticket System

Credits

Born from discussions in TechOverflow with vichannnnn, MrMarciaOng, and nasdin.

Agent collection from wshobson/agents.

Security workflow and /secops skill contribution by Ciaran Hughes.

License

MIT