@jojonax/codex-copilot 1.5.3 → 1.6.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Jonas Qin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Jonas Qin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,25 @@
 # Codex-Copilot 🤖
 
-**PRD-driven automated development orchestrator for CodeX / Cursor**
+**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, breaks them into tasks, drives CodeX/Cursor to develop each feature, submits PRs, waits for AI code review, fixes issues, and merges — all in a loop.
+Turn your PRD into working code — automatically. Codex-Copilot reads your product requirement docs, decomposes them into tasks, 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 → CodeX Dev → PR → AI Review → Fix → Merge → Next Task
+PRD → Tasks → 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
 
 ```bash
@@ -18,7 +30,7 @@ npm install -g @jojonax/codex-copilot
 npx @jojonax/codex-copilot
 
 # In your project directory:
-codex-copilot init    # Detect PRD, generate task queue
+codex-copilot init    # Detect PRD, choose AI provider, generate task queue
 codex-copilot run     # Start the automated dev loop
 ```
 
@@ -27,49 +39,95 @@ codex-copilot run     # Start the automated dev loop
 ### 1. `codex-copilot init`
 
 - 🔍 **Auto-detects PRD** files in your project (by filename, size, content keywords)
-- 📋 Generates a task decomposition prompt for CodeX
+- 🤖 **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. Execute the PRD prompt in CodeX
-
-- Paste the generated prompt into CodeX desktop (or use CodeX CLI if available)
-- CodeX breaks down your PRD into ordered, independent tasks → `tasks.json`
-
-### 3. `codex-copilot run`
+### 2. `codex-copilot run`
 
 Loops through each task in 4 phases:
 
 | Phase | What Happens |
 |-------|-------------|
-| **1. Develop** | Creates feature branch, generates dev prompt, copies to clipboard |
-| **2. PR** | Auto commits, pushes, creates GitHub PR via `gh` CLI |
-| **3. Review** | Polls for AI review (Gemini Code Assist), collects feedback |
+| **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 |
 
-### Other Commands
+### 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 status   # Progress bar + task list
-codex-copilot reset    # Reset and start over
+codex-copilot init        # Initialize project (auto-detect PRD, generate task queue)
+codex-copilot run         # Start automated development loop
+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 fix         # Repair corrupted project files + git state
+codex-copilot reset       # Reset state and start over
+codex-copilot update      # Update to latest version
 ```
 
 ## Prerequisites
 
-| Tool | Install |
-|------|---------|
-| Node.js ≥ 18 | `brew install node` |
-| GitHub CLI | `brew install gh && gh auth login` |
-| [Gemini Code Assist](https://github.com/marketplace/gemini-code-assist) | Install on your GitHub repo |
-| CodeX Desktop / Cursor | Official installer |
+| 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
-- **🔄 Breakpoint Resume** — `state.json` persists progress; interrupted runs continue from last task
-- **📋 Clipboard Integration** — auto-copies prompts to clipboard (macOS `pbcopy`)
-- **🤖 Dual Mode** — full-auto with CodeX CLI, or manual clipboard mode for desktop app
-- **🔁 Review Loop** — max 2 rounds of AI review + fix, with human override options
-- **⚙️ Configurable** — edit `.codex-copilot/config.json` for timeouts, branch names, review rounds
+- **🤖 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
+
+### 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
+- **⏱️ 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
 
@@ -77,47 +135,89 @@ After `init`, edit `.codex-copilot/config.json`:
 
 ```json
 {
+  "provider": "codex-cli",
   "base_branch": "main",
   "max_review_rounds": 2,
   "review_poll_interval": 60,
-  "review_wait_timeout": 600
+  "review_wait_timeout": 600,
+  "weekly_quota_threshold": 97,
+  "auto_evolve": true
 }
 ```
 
+| Field | Default | Description |
+|-------|---------|-------------|
+| `provider` | `codex-cli` | AI provider ID (see Supported Providers) |
+| `base_branch` | `main` | Branch to create feature branches from |
+| `max_review_rounds` | `2` | Max review-fix cycles per task (hard cap: 5) |
+| `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 after all tasks complete |
+
 ## Project Structure
 
 ```
-.codex-copilot/           # Created in your project
-├── config.json           # Settings
-├── state.json            # Run state (auto-managed)
-├── tasks.json            # Task queue (CodeX-generated)
-├── codex-instructions.md # CodeX system prompt
-└── _current_prompt.md    # Current prompt (auto-copied to clipboard)
+.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
+├── 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
+  ├── 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
+  │   ├── Checkpoint ──── Fine-grained resume (task → phase → step)
+  │   └── Self-Heal ───── Pre-flight checks, lock cleanup, index repair
+  ├── evolve ───────────── Archive round → Gap analysis → Plan next → Auto-run
+  ├── usage ────────────── Multi-provider token/quota dashboard
+  └── fix ──────────────── JSON schema repair + git state recovery
 ```
 
 ## How the Review Loop Works
 
 ```
-CodeX develops feature
+AI develops feature
+        ↓
+   Push + Create PR (with multi-level recovery)
         ↓
-   Push + Create PR
+   Wait for AI Review (polling + proactive checks)
         ↓
-   Wait for AI Review (Gemini Code Assist)
+   Classify feedback via AI (pass/fix/ambiguous)
         ↓
-  ┌─ APPROVED → Merge → Next Task
-  └─ CHANGES_REQUESTED → Collect feedback
+  ┌─ PASS → Merge → Next Task
+  └─ FIX → Collect specific feedback
         ↓
-   Generate fix prompt → CodeX fixes
+   Generate targeted fix prompt → AI fixes
         ↓
-   Push → Wait for re-review
+   Push → Request re-review → Wait
         ↓
-   (max 2 rounds, then human decides)
+   (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)
 - [ ] Support for more AI review tools (CodeRabbit, GitHub Copilot Review)
-- [ ] Built-in task decomposition (no manual CodeX step)
 - [ ] Web dashboard for monitoring multiple projects
 - [ ] GitHub Action for fully server-side automation
 - [ ] Support for monorepo / multi-package projects