https://github.com/efaulhaber/codex-pr-review
A Bash tool that uses Codex CLI to review GitHub PRs and publish review comments to GitHub..
https://github.com/efaulhaber/codex-pr-review
bash code-review codex codex-cli github github-cli
Last synced: about 1 month ago
JSON representation
A Bash tool that uses Codex CLI to review GitHub PRs and publish review comments to GitHub..
- Host: GitHub
- URL: https://github.com/efaulhaber/codex-pr-review
- Owner: efaulhaber
- License: mit
- Created: 2026-06-02T12:32:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-03T14:38:22.000Z (about 1 month ago)
- Last Synced: 2026-06-03T16:17:21.955Z (about 1 month ago)
- Topics: bash, code-review, codex, codex-cli, github, github-cli
- Language: Shell
- Homepage:
- Size: 25.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# codex-pr-review
`codex-pr-review.sh` runs Codex against a GitHub pull request diff and posts the result as a GitHub pull request review.
It uses Codex CLI to work with included quota of a ChatGPT subscription instead of OpenAI API billing, and it uses GitHub CLI to post reviews.
The script checks out the pull request head in a temporary detached worktree, runs several focused Codex passes against the pull request base branch, asks Codex to merge the findings of the individual passes, and posts any diagnostics as inline review comments.
## Requirements
- `bash`
- `git`
- `gh`
- `jq`
- `codex`
- GitHub CLI authentication with a token that can read the repository and create pull request reviews
- Codex CLI authentication through saved ChatGPT/Codex auth
The script unsets `OPENAI_API_KEY` and `CODEX_API_KEY` before invoking Codex so that the Codex CLI uses saved account authentication instead of OpenAI API billing.
For review execution, it creates a temporary `CODEX_HOME` and copies only top-level Codex auth files into it, so personal Codex or VS Code extension instructions are not loaded.
## Setup
1. Install and authenticate the required tools:
```bash
gh auth login
codex login
```
2. Make sure the script is executable:
```bash
chmod +x ./codex-pr-review.sh
```
3. Use the script from any directory inside the Git repository that contains the pull request you want to review. The script resolves the repository root with `git rev-parse --show-toplevel`.
For forked repositories, it might be necessary to first run `gh repo set-default` to set the repository context for GitHub CLI.
See `gh repo set-default --help` for details.
## Usage
Before running a review, change into the Git repository that contains the pull request.
Make sure GitHub CLI and Codex CLI are authenticated; run `gh auth login` and `codex login` if needed.
Review pull request `123` and post the review to GitHub:
```bash
./codex-pr-review.sh 123
```
Optionally, create an alias for the script by adding the following line to `~/.bash_profile`:
```bash
alias review="~/git/codex-pr-review/codex-pr-review.sh"
```
Then, the review command becomes:
```bash
review 123
```
Run without posting anything:
```bash
DRY_RUN=1 review 123
```
## Custom Review Instructions
Repository-specific review instructions can be stored next to `codex-pr-review.sh` in the `custom-instructions` directory.
The script looks for a Markdown file named after the GitHub repository slug:
```text
/custom-instructions//.md
```
For example, reviews for `efaulhaber/codex-pr-review` load:
```text
/custom-instructions/efaulhaber/codex-pr-review.md
```
When a matching file exists, its contents are included in each Codex review pass and in the final synthesis prompt.
The terminal output reports whether custom instructions were loaded or no matching file was found.
## What Gets Posted
The posted review includes:
- A top-level `Codex Review` body with a factual Markdown summary of the pull request changes.
- An AI-generated review notice and a small `codex-pr-review` attribution link.
- Inline comments for diagnostics that Codex ties to changed lines in the pull request diff.
Diagnostics use these severities:
- `HIGH` for likely bugs, security issues, or data-loss issues.
- `MEDIUM` for important risks.
- `LOW` for remaining issues.
The posted review is created with GitHub's `COMMENT` event, so it does not approve the pull request or request changes.
## Security
- The script runs Codex with isolated settings to ignore local custom instructions.
- Codex passes run with `--ephemeral --ignore-user-config --ignore-rules --sandbox read-only` against a temporary detached worktree and temporary auth-only `CODEX_HOME`.
- The final synthesis pass uses the same isolation flags.
- The temporary worktree and intermediate files are removed when the script exits.
- GitHub API requests use the local `gh` authentication token through `GITHUB_TOKEN`.
## Notes
- For forked repositories, it might be necessary to first run `gh repo set-default`
to set the repository context for GitHub CLI.
## License
MIT License. See [LICENSE](LICENSE).