Codex-Copilot 馃

PRD-driven automated development orchestrator 鈥?works with any AI coding tool

Turn your PRD into working code 鈥?automatically. Codex-Copilot reads your product requirement docs, decomposes them into tasks, reviews the decomposition via multi-agent evaluation, drives your AI coding tool to develop each feature, submits PRs, waits for AI code review, fixes issues, and merges 鈥?all in a fully automated loop.

PRD 鈫?Tasks 鈫?Multi-Agent Review 鈫?AI Dev 鈫?PR 鈫?AI Review 鈫?Fix 鈫?Merge 鈫?Next Task 鈫?Evolve 鈫?Repeat

Supported AI Providers

| Provider | Mode | How it works | |----------|------|-------------| | Codex CLI | Full-auto | Pipes prompt via stdin (codex exec --full-auto) | | Claude Code | Full-auto | -p mode with --allowedTools permissions | | Cursor Agent | Full-auto | Headless -p mode | | Gemini CLI | Full-auto | Non-interactive -p prompt execution | | Codex Desktop | Auto-paste | Detects running IDE, auto-pastes prompt | | Cursor IDE | Auto-paste | Detects running IDE, auto-pastes prompt | | Antigravity | Auto-paste | Detects running IDE, auto-pastes prompt |

Quick Start

# Install globally
npm install -g @jojonax/codex-copilot

# Or run directly without installing
npx @jojonax/codex-copilot

# In your project directory:
codex-copilot init    # Detect PRD, choose AI provider, generate task queue
codex-copilot run     # Start the automated dev loop
codex-copilot run --stop-after-round  # Finish current round and stop (skip evolve)

init and run perform a preflight version check. If a newer npm release exists, Codex-Copilot auto-updates itself before continuing the command.

How It Works

1. codex-copilot init

• 馃攳 Auto-detects PRD files in your project (by filename, size, content keywords)
• 馃 Multi-provider selection 鈥?detects installed AI tools with version info and update status
• 馃搵 Generates a task decomposition prompt and invokes the AI to create tasks.json
• 馃梻锔?Creates .codex-copilot/ with config, state, and instructions

2. codex-copilot run

Loops through each task in 4 phases:

| Phase | What Happens | |-------|-------------| | 1. Develop | Creates feature branch, generates dev prompt, executes via AI provider | | 2. PR | Auto commits, pushes, creates GitHub PR with recovery handling | | 3. Review | Polls for AI review, classifies feedback, determines actionability | | 4. Merge | Squash merges after approval, moves to next task |

Run completion behavior:

• Before evolve, run performs an in-round self-check sweep: unresolved blocked/pending tasks are retried in task order with an internal safety cap.
• evolve triggers only when the round is truly converged (no blocked, pending, or in_progress tasks).
• Use codex-copilot run --stop-after-round (aliases: --once, --no-evolve) to finish the current round and stop without entering evolve.
• Local merge policy can be selected per run:
  • default: per-task merge (review passed -> merge to base immediately)
  • relaxed: codex-copilot run --loose-merge / --merge-per-round (merge once at round end)
  • run startup performs a branch reconciliation sweep to merge previously completed task branches into base.

3. codex-copilot evolve

Multi-round PRD iteration 鈥?the killer feature:

Run completes 鈫?Archive round 鈫?Gap analysis against PRD 鈫?Plan next batch 鈫?Generate new tasks.json 鈫?Auto-start next round

Evolve compares completed features against the full PRD, identifies gaps, plans the next batch of 8-15 tasks, and automatically starts execution. Rounds continue until the PRD is fully implemented.

All Commands

codex-copilot init        # Initialize project (auto-detect PRD, generate task queue)
codex-copilot run         # Start automated development loop
codex-copilot run --stop-after-round  # Finish this round and stop before evolve
codex-copilot run --loose-merge  # Relaxed mode: merge completed local branches once per round
codex-copilot status      # View current task progress with progress bar
codex-copilot evolve      # Start next PRD iteration round (gap analysis 鈫?plan 鈫?run)
codex-copilot retry       # Retry blocked tasks with enhanced prompts
codex-copilot skip <id>   # Force-skip a task to unblock dependents
codex-copilot usage       # Show AI token usage across all providers
codex-copilot report      # Show persistent development report (summary/round/task)
codex-copilot model       # Interactive model picker (arrow keys + Enter) for current provider
codex-copilot fix         # Repair corrupted project files + git state
codex-copilot reset       # Reset state and start over
codex-copilot update      # Update to latest version

Prerequisites

| Tool | Required | Install | |------|----------|---------| | Node.js 鈮?18 | 鉁?| brew install node / nodejs.org | | GitHub CLI | 鉁?| brew install gh && gh auth login / cli.github.com | | Git | 鉁?| Auto-installed on Windows if missing (see below) | | AI Code Review bot | Recommended | Gemini Code Assist or similar | | Any AI coding tool | 鉁?| Codex / Claude / Cursor / Gemini CLI |

Windows Support

Codex-Copilot uses POSIX shell commands internally. On Windows, it automatically detects and configures Git for Windows:

1. Checks if sh is already in PATH
2. Scans common Git installation paths (Program Files, Scoop, Chocolatey)
3. Discovers via where git and GIT_INSTALL_ROOT environment variable
4. If not found, offers to auto-install Git for Windows via winget or direct download
5. After installation, refreshes PATH from the Windows registry 鈥?no terminal restart needed

Features

Core Automation

• 馃攳 Smart PRD Detection 鈥?scans project dirs, scores candidates by filename pattern + content analysis
• 馃 7 AI Providers 鈥?full-auto CLI execution or auto-paste for desktop IDEs
• 馃攧 Multi-Round Evolution 鈥?gap analysis + re-planning across unlimited rounds until PRD is fully built
• 馃搵 AI Review Classification 鈥?uses AI to determine if review feedback is actionable vs informational
• 馃攳 Multi-Agent Task Review 鈥?3 independent review agents (Coverage, Clarity, Feasibility) evaluate task decomposition quality with auto-revision
• 馃搫 AGENTS.md Integration 鈥?reads project AGENTS.md as context for all prompts, writes development summaries back after each round

Reliability

• 馃捑 Fine-Grained Checkpoints 鈥?resumes from exact sub-step (branch created? prompt generated? AI complete?)
• 馃敡 Self-Healing 鈥?pre-flight checks, auto-repair corrupted JSON, git state recovery
• 馃攣 Auto-Retry 鈥?blocked tasks automatically retry on next run with preserved branches
• 馃 Round Self-Check Sweep 鈥?retries unresolved tasks inside the same round before allowing evolve
• 馃敡 Startup Auto-Update 鈥?init and run auto-upgrade to latest npm release before execution
• 馃寛 Branch Reconciliation 鈥?startup and round-end merge sweeps auto-merge completed branches into base (with conflict auto-resolution)
• 鈴憋笍 Rate Limit Recovery 鈥?detects rate limits, waits for reset, auto-resumes
• 馃洝锔?Quota Guard 鈥?checks weekly quota before execution, stops if threshold exceeded
• 鈴?AI Timeout Protection 鈥?30-minute timeout prevents infinite hangs

Developer Experience

• 馃搳 Multi-Provider Usage Dashboard 鈥?token breakdown for Codex, Claude, Cursor with cache rates and quota tracking
• 馃敡 File Repair Tool 鈥?deep JSON corruption recovery + git state healing (locks, detached HEAD, stale indexes)
• 馃搵 Clipboard Integration 鈥?auto-copies prompts on macOS (pbcopy), Linux (xclip/xsel), and Windows (clip)
• 馃獰 Windows Auto-Bootstrap 鈥?auto-detects or installs Git for Windows, no manual PATH configuration needed
• 鈿欙笍 Configurable 鈥?timeouts, branch patterns, review rounds, quota thresholds, auto-evolve toggle

Git & PR Management

• 馃攢 Auto Branch Management 鈥?creates feature branches, handles checkout failures gracefully
• 馃摑 PR with Recovery 鈥?creates PR 鈫?finds existing 鈫?fixes remote 鈫?retry (multi-level fallback)
• 馃攳 Re-Review Requests 鈥?automatically requests fresh review after fix pushes
• 馃敀 Private Repo Aware 鈥?adds [skip ci] to commits in private repos to save CI minutes

Configuration

After init, edit .codex-copilot/config.json:

{
  "provider": "codex-cli",
  "model": "gpt-5-codex",
  "base_branch": "main",
  "max_review_rounds": 2,
  "review_poll_interval": 60,
  "review_wait_timeout": 600,
  "weekly_quota_threshold": 97,
  "auto_evolve": true
}

| Field | Default | Description | |-------|---------|-------------| | provider | codex-cli | AI provider ID (see Supported Providers) | | model | provider default | Default model for the selected provider (set via codex-copilot model, arrow-key picker) | | provider_models | {} | Optional per-provider model map for multi-provider review chains | | base_branch | main | Branch to create feature branches from | | max_review_rounds | 2 | Max review-fix cycles per task (hard cap: 5) | | local_merge_mode | task | Local-mode branch merge policy: task (default) or round | | review_poll_interval | 60 | Seconds between review status checks | | review_wait_timeout | 600 | Max seconds to wait for initial review | | weekly_quota_threshold | 97 | Stop execution when weekly quota exceeds this % | | auto_evolve | true | Auto-start next round only after current round fully converges (and no run --stop-after-round override) | | review_threshold | 7 | Minimum score (1-10) to pass multi-agent task review |

Model fallback behavior:

• If the active model is temporarily at capacity, codex-copilot waits and retries the same model first.
• If it is still unavailable, codex-copilot tries fallback models with an internal safety-first policy (no user tuning).
• After fallback succeeds, codex-copilot temporarily uses that fallback and later probes back to your preferred configured model automatically.

Project Structure

.codex-copilot/                # Created in your project
鈹溾攢鈹€ config.json                # Settings (provider, branch, timeouts)
鈹溾攢鈹€ state.json                 # Checkpoint state (auto-managed)
鈹溾攢鈹€ tasks.json                 # Current round's task queue
鈹溾攢鈹€ rounds.json                # Multi-round evolution history
鈹溾攢鈹€ tasks_round_N.json         # Archived task queues from previous rounds
鈹溾攢鈹€ report.json                # Persistent structured development report
鈹溾攢鈹€ report.md                  # Human-readable report mirror (auto-generated)
鈹溾攢鈹€ codex-instructions.md      # AI system prompt
鈹溾攢鈹€ parse-prd-prompt.md        # PRD decomposition prompt
鈹溾攢鈹€ evolve-prompt.md           # Gap analysis prompt (auto-generated)
鈹斺攢鈹€ _current_prompt.md         # Active prompt (auto-copied to clipboard)

Architecture

CLI Entry (bin/cli.js)
  鈹溾攢鈹€ Shell Bootstrap 鈹€鈹€鈹€鈹€ Auto-detect/install sh on Windows
  鈹溾攢鈹€ init 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ PRD detection 鈫?Provider selection 鈫?Task decomposition
  鈹?  鈹溾攢鈹€ AGENTS.md 鈹€鈹€鈹€鈹€ Read project context 鈫?inject into prompts
  鈹?  鈹斺攢鈹€ Review 鈹€鈹€鈹€鈹€鈹€鈹€鈹€ Multi-Agent (Coverage/Clarity/Feasibility) 鈫?auto-revise
  鈹溾攢鈹€ run 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ 4-phase loop: Develop 鈫?PR 鈫?Review 鈫?Merge
  鈹?  鈹溾攢鈹€ Provider 鈹€鈹€鈹€鈹€鈹€鈹€ Execute via CLI (piped) or IDE (auto-paste/clipboard)
  鈹?  鈹溾攢鈹€ Git 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ Branch, commit, push, checkout
  鈹?  鈹溾攢鈹€ GitHub 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ PR create/find, review polling, feedback collection
  鈹?  鈹溾攢鈹€ AGENTS.md 鈹€鈹€鈹€鈹€ Inject context into dev/fix prompts 鈫?write summary
  鈹?  鈹溾攢鈹€ Checkpoint 鈹€鈹€鈹€鈹€ Fine-grained resume (task 鈫?phase 鈫?step)
  鈹?  鈹斺攢鈹€ Self-Heal 鈹€鈹€鈹€鈹€鈹€ Pre-flight checks, lock cleanup, index repair
  鈹溾攢鈹€ evolve 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ Archive round 鈫?Gap analysis 鈫?Review 鈫?Plan 鈫?Auto-run
  鈹?  鈹溾攢鈹€ AGENTS.md 鈹€鈹€鈹€鈹€ Inject context 鈫?write round summary
  鈹?  鈹斺攢鈹€ Review 鈹€鈹€鈹€鈹€鈹€鈹€鈹€ Multi-Agent evaluation of new task batch
  鈹溾攢鈹€ usage 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ Multi-provider token/quota dashboard
  鈹斺攢鈹€ fix 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€ JSON schema repair + git state recovery

How the Review Loop Works

AI develops feature
        鈫?   Push + Create PR (with multi-level recovery)
        鈫?   Wait for AI Review (polling + proactive checks)
        鈫?   Classify feedback via AI (pass/fix/ambiguous)
        鈫?  鈹屸攢 PASS 鈫?Merge 鈫?Next Task
  鈹斺攢 FIX 鈫?Collect specific feedback
        鈫?   Generate targeted fix prompt 鈫?AI fixes
        鈫?   Push 鈫?Request re-review 鈫?Wait
        鈫?   (auto-extends up to 5 rounds, then blocks for human)

Roadmap

• [x] Multi-provider support (Codex, Claude, Cursor, Gemini, IDE auto-paste)
• [x] Multi-round PRD evolution with gap analysis
• [x] AI-powered review classification
• [x] Rate limit detection and auto-recovery
• [x] Quota pre-check and protection
• [x] Self-healing file repair and git state recovery
• [x] Cross-platform support (macOS, Linux, Windows)
• [x] Multi-Agent Task Review (Coverage/Clarity/Feasibility with auto-revision)
• [x] AGENTS.md full-lifecycle integration (read context 鈫?inject prompts 鈫?write summaries)
• [ ] Support for more AI review tools (CodeRabbit, GitHub Copilot Review)
• [ ] Web dashboard for monitoring multiple projects
• [ ] GitHub Action for fully server-side automation
• [ ] Support for monorepo / multi-package projects

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feat/awesome)
3. Commit your changes (git commit -m 'feat: add awesome feature')
4. Push and open a PR

License

MIT 漏 Jonas Qin