🔁 GitHub Codex PR Loop

Let Codex handle the pull-request review loop.

This skill keeps a pull request moving through review, fixes, and re-review without letting the process run forever or merge code on its own.

In practical terms, it can:

1. 📂 Open or reuse a GitHub pull request.
2. 🙋🏽 Ask @codex to review the current version of the code.
3. 🛠️ Fix feedback that is clear and within the task you approved.
4. 🖲️ Run the repository's validation commands.
5. ↗️ Push the fix and ask Codex to review again.
6. 🏁 Stop when the latest review is clear, a safety check fails, or the loop reaches its limit.

ℹ️ Independent project: This community project is not affiliated with, endorsed by, or supported by OpenAI or GitHub.

🤷🏽‍♀️ Why use it?

A pull-request review is rarely one step:

Open PR → request review → read feedback → make fixes → test → push → request review again

Doing that by hand is repetitive. It is also easy to accidentally treat an old review as if it covered newer code. This skill keeps the loop organized and ties every review to the exact version of the code that Codex reviewed.

The result is a repeatable workflow with clear limits, not an agent that keeps changing your repository indefinitely.

🤔 What does “the exact version” mean?

Git gives every commit a unique ID called a SHA. You can think of it as the version number for one exact snapshot of your code.

If the code changes, the SHA changes. The skill checks that a “looks good” review belongs to the newest SHA, not an older version from before the latest fix.

The skill's precise terminal statement is:

No remaining actionable Codex findings for SHA `<full-sha>`.

In plain English: Codex reviewed that exact commit and did not leave any feedback that this skill can act on.

It does not mean the code is guaranteed correct, secure, approved by a human, or ready to merge. Tests, CI, required approvals, branch protection, merge conflicts, and non-Codex review threads are still separate checks.

🎛️ Choose a mode

Mode	Best for	What happens
approval-gated	First-time use, important repositories, or anyone who wants control	Codex shows the planned write actions and pauses for approval. If the plan or repository changes, the old approval no longer counts.
autonomous	Familiar repositories where you want the loop to run hands-off	Codex performs the authorized review-and-fix steps without asking before every batch. The same safety checks and hard limits still apply.
report-only	Checking an existing PR without changing anything	Codex reads the PR and reports its current state once. It does not run local Git or repository code, edit files, write to GitHub, or manage an Automation.

Not sure which one to use? Start with approval-gated.

If you do not name a mode, v0.1.0 uses autonomous for backward compatibility. First-time users should still choose approval-gated explicitly.

💬 Example prompts

The skill runs only when you invoke $github-codex-pr-loop by name. Installing it does not make it run automatically.

Open a PR and approve each write batch:

Use $github-codex-pr-loop in approval-gated mode to push these changes as a PR against main.

Run the bounded loop without per-batch approval:

Use $github-codex-pr-loop in autonomous mode to push these changes as a PR against main.

Inspect an existing PR without changing it:

Use $github-codex-pr-loop in report-only mode on the existing PR against main.

Always name the base branch, such as main, explicitly.

🛡️ Built-in limits

• One main @codex review request per round.
• Up to 60 minutes for Codex to answer each request.
• At most five successfully pushed feedback-fix rounds in one run.
• The first PR push is round zero and does not count as a feedback-fix round.
• The skill stops instead of guessing when repository state, the PR branch, authentication, validation, or review feedback is unclear.
• Stopping prevents further writes; it does not undo safe writes that already completed, such as a branch, commit, PR, or review request.
• The skill never merges, force-pushes, replaces remotes, retargets a PR, deletes branches, or resolves human-authored review threads.

✅ Requirements for v0.1.0

For every mode:

• Codex with Skills.
• The GitHub plugin, including $github:gh-address-comments.
• Python 3.10 or newer.
• A GitHub.com repository where @codex pull-request review is available.
• A same-repository pull request, either already open or created by the skill. report-only requires an existing PR.

For approval-gated and autonomous modes:

• Local git.
• An authenticated GitHub CLI (gh).
• Codex Automations.
• Read-only access to Codex's documented Automation registry so the skill can find the Automation it owns. Automation changes still go through the Codex tool; the skill does not edit registry files directly.

Not supported in v0.1.0:

• GitHub Enterprise Server.
• GitLab or Bitbucket.
• Pull requests from a fork into an upstream repository.
• Repositories that cannot provide the documented safe execution boundary without explicit risk acceptance.

📦 Install v0.1.0

Ask Codex:

Use $skill-installer to install the skill from https://github.com/vicc/github-codex-pr-loop-skill/tree/v0.1.0/github-codex-pr-loop

The installer puts the skill in $CODEX_HOME/skills/github-codex-pr-loop—normally ~/.codex/skills/github-codex-pr-loop—and will not overwrite an existing installation. The skill becomes available on the next Codex turn.

While this repository is private, installation requires existing GitHub credentials or a fine-grained token with read-only Contents access to the repository. Never paste a token into a prompt. No repository credential will be needed after the repository becomes public.

🔧 What can it change?

In a write-capable mode, and only within the task you authorized, the skill may:

• Create a branch and commits.
• Push to the selected same-repository branch.
• Open or reuse a matching pull request.
• Post the review request and bounded follow-up comments.
• Apply and validate fixes for actionable Codex feedback.
• Manage the heartbeat Automation created or safely reused for this PR loop.
• Mark an authorized draft PR ready during finalization; merge gates are checked and reported separately.
• Resolve only addressed review threads rooted in Codex feedback.

In report-only mode, none of those writes are allowed.

Repository files, PR descriptions, review comments, linked content, and test output are treated as untrusted input. They can describe a bug, but they cannot grant new permissions, request secrets, or expand the task.

The skill uses a restricted Git and repository-code execution profile. It limits filesystem access, disables risky Git hooks and helpers, and avoids exposing unrelated credentials or home-directory data. If it cannot establish the required boundary, it stops and explains the exact missing guarantees. Continuing requires your explicit acceptance of those exact risks; autonomous mode does not imply that acceptance.

These workflow safeguards are not their own operating-system or GitHub permission sandbox. Use the least-privileged credentials that support the requested work and follow your organization's code-handling policy.

Technical protocol details for maintainers and security reviewers

The machine-readable policy is github-codex-pr-loop/references/loop-policy.json. The exact approval payloads are documented in manifest-schema.md, and the sanitized Git profile is documented in git-execution-boundary.md.

evaluate_state.py is the decision gate used before the initial write and on Automation wakeups. It has no third-party Python dependencies and performs no Git, GitHub, network, or Automation operations itself. The evaluator pins every schema-v1 policy field, value, and type in code; --policy accepts only that exact policy and cannot be used to relax the limits.

Canonical loop and request keys detect duplicate Automations and replayed mutations; they are not a distributed lock. The owned heartbeat schedule must remain exactly FREQ=MINUTELY;INTERVAL=2.

A trusted Codex response must come from the expected GitHub Bot account, match the canonical request, refer to the requested head SHA, and fall inside that request's response window. Edited responses and later contradictions are re-evaluated.

Before any initial side effect, the evaluator validates the complete initial snapshot, operation plan, execution boundary, and their hashes. In approval-gated mode, approval is bound to that exact plan hash. A changed branch, base tip, diff, path, command, Git configuration, filesystem scope, or operation invalidates the approval.

After a push, a post-write receipt cross-checks the approved diff and paths against the final local branch, remote branch, PR head, clean worktree, ancestry proof, and rendered review request. Finalization is a second evaluation after the skill refreshes the PR, review, thread, draft, and gate state.

Any unexpected drift, duplicate Automation, schedule mismatch, authentication failure, ambiguous feedback, failed validation, or evaluator error stops writes. An evaluator error never allows Git or GitHub writes or Automation deletion; the only mutation exception is pausing the one freshly verified Automation owned by this exact run.

👮🏽‍♂️ Validate the skill

Run:

python3 tests/check_skill.py

The test suite uses only the Python standard library. It checks the skill contract and its public lifecycle fixtures, but it does not simulate GitHub, Codex, or Automations end to end.

📄 License

MIT