codex-project-pilot

Codex Project Pilot

简体中文 · Quick start · Architecture

An open-source, issue-driven delivery kit for Codex. Turn a product brief into a traceable GitHub roadmap, let Codex implement one accepted issue at a time, map the codebase with codebase-memory-mcp, and run OpenCodeReview before a pull request is merged.

Codex Project Pilot is an independent community project. It is not affiliated with or endorsed by OpenAI, Alibaba, or DeusData.

What it does

Product brief
   │
   ▼
Plan Project workflow ──► Roadmap issue + ordered implementation issues
                                      │
                                      ▼
                              ready-for-agent
                                      │
                                      ▼
Codex ──► codebase-memory map ──► implementation ──► tests ──► OpenCodeReview
                                      │
                                      ▼
                                 Pull request
                                      │
                         human merge (default)
                                      │
                                      ▼
                               dispatch next issue

• Traceable by default: requirements, decisions, code, CI, review, and release stay linked through Issues and PRs.
• One issue at a time: dependency ordering and concurrency controls reduce conflicting agent work.
• Repository-aware: codebase-memory-mcp gives Codex a structural code map before it edits.
• Review gate: OpenCodeReview produces a deterministic review manifest and feeds its findings back to Codex.
• Human control: merging is manual by default; optional auto-merge is an explicit repository variable.
• Low lock-in: workflows, prompts, schemas, labels, and scripts live in the repository.

Five-minute start

Requirements: GitHub CLI, Git, Python 3.10+, and a Codex/OpenAI API key for GitHub Actions.

gh repo create my-product --public --template hexf11/codex-project-pilot --clone
cd my-product
./scripts/bootstrap.sh
printf '%s' "$OPENAI_API_KEY" | gh secret set OPENAI_API_KEY

Then open Actions → Plan project → Run workflow, enter your product brief, and review the Issues it creates. The first issue is dispatched automatically; every following issue is dispatched after the current PR is merged.

For a local-first flow, open the repository in Codex and use:

Read AGENTS.md. Turn the following product request into a GitHub roadmap and small,
testable Issues. Do not implement until the roadmap and acceptance criteria exist.
Then take only the oldest dependency-free issue labeled ready-for-agent, map the
repository with codebase-memory-mcp, implement it, run the configured checks and
OpenCodeReview, and prepare a PR that closes the issue.

Product request:
<describe the product and constraints here>

Required secret and optional variables

Name	Type	Purpose
OPENAI_API_KEY	Actions secret	Runs openai/codex-action@v1 in planning, implementation, and review jobs.
AGENT_AUTO_MERGE	Repository variable	Set to true only if branch protection and required checks are configured. Default: false.
PROJECT_PILOT_MODEL	Repository variable	Optional Codex model override.
PROJECT_PILOT_EFFORT	Repository variable	Optional reasoning effort override. Default in workflows: high.

Workflow states

agent:queued → ready-for-agent → agent:running → agent:review → closed

Failures move the issue to agent:blocked and add a diagnostic comment. Re-running the issue workflow is idempotent: it reuses agent/issue-<number> and updates the existing PR.

Repository contents

• .github/workflows/plan-project.yml — turns a brief into a validated JSON plan and GitHub Issues.
• .github/workflows/agent-issue.yml — implements one trusted issue and opens or updates its PR.
• .github/workflows/agent-review.yml — read-only Codex + OpenCodeReview PR review.
• .github/workflows/dispatch-next.yml — advances the queue after a merge.
• .github/codex/prompts/ — versioned agent contracts.
• .project-pilot/config.json — project-pilot settings.
• .project-pilot/checks.sh — project-specific validation commands.
• AGENTS.md — persistent instructions automatically read by Codex.
• scripts/ — zero-dependency GitHub API and validation utilities.

Boundaries

This kit improves process and traceability; it does not make unspecified requirements correct. Keep production credentials out of Issues, require branch protection for important repositories, review schema/database/security changes, and test deployments in an isolated environment.

License

MIT. Third-party tools retain their own licenses.