npm package: @jojonax/codex-copilot
Description: PRD-driven automated development orchestrator 鈥?works with any AI coding tool
Author: jojonax
Latest version: 1.13.12

﻿# 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 -a never exec --sandbox danger-full-access`) |
| **Claude Code** | Full-auto | `-p` mode with full `--allowedTools` (`Bash(*),Read,Write,Edit`) |
| **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

```bash
# 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 --multi-round  # Continue evolving into next rounds automatically
```

`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

#### Copilot Main Flow (Opt-in)

- `copilot-cli` and `codex-cli` are auto-detected and connected when available.
- Copilot main flow is **disabled by default** (`main_flow_enabled=false`).
- Existing/default run behavior is preserved unless the user explicitly enables Copilot main flow during `init`.
- When enabled:
  - Planning model default: `claude-opus-4.6`
  - Execution model default: `claude-sonnet-4.6`
  - `ask_user` continuation in planning/final-check/cluster execution stays in the same Copilot session (`--continue`) and is counted as **1 premium request unit per conversation**.

### 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).
- Default `codex-copilot run` behavior is single-round: finish current round and stop.
- Use `codex-copilot run --multi-round` (alias: `--evolve`) to keep evolving into the next rounds automatically.
- Legacy single-round aliases are still accepted: `--stop-after-round`, `--once`, `--no-evolve`.
- Local merge policy can be selected per run:
  - default: per-round merge (`all tasks in current round converge -> merge completed branches into base`)
  - strict: `codex-copilot run --strict-merge` / `--merge-per-task` (merge each task immediately after review passes)
  - 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

```bash
codex-copilot init        # Initialize project (auto-detect PRD, generate task queue)
codex-copilot run         # Run one full round (default)
codex-copilot run --multi-round  # Keep evolving across rounds automatically
codex-copilot run --strict-merge # Strict mode: merge each task branch right after it passes
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](https://nodejs.org) |
| GitHub CLI | 鉁?| `brew install gh && gh auth login` / [cli.github.com](https://cli.github.com) |
| Git | 鉁?| Auto-installed on Windows if missing (see below) |
| AI Code Review bot | Recommended | [Gemini Code Assist](https://github.com/marketplace/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`:

```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` | `round` | Local-mode branch merge policy: `round` (default) or `task` |
| `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` | When multi-round is enabled (`run --multi-round` or `evolve`), auto-start next round only after current round fully converges |
| `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.

Environment overrides:
- `CODEX_COPILOT_ASCII_LOGS`: force ASCII progress rendering (`1` = ASCII, `0` = allow Unicode on Windows).

## 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