Codex Guard — quality gate for AI-generated pull requests

What it does

Runs on pull_request, figures out whether the PR looks agent-written (label, branch prefix, or title), and gates it on four deterministic checks — so human-authored PRs pass untouched by default, and only agent PRs get the gate:

Check	What it flags
🧹 TODO scan	`TODO / FIXME / XXX / HACK / WIP` on added lines only
🔐 Secret scan	AWS / GitHub / Google / OpenAI / Anthropic / Slack / Stripe keys, hardcoded credentials, connection strings — values redacted
💬 Commit hygiene	Non-conventional and empty commit subjects
🧪 CI status	Failing status checks or check runs on the PR head commit

Every finding lands as a file/line check-run annotation plus one living report comment that updates in place. Optionally submits a formal REQUEST_CHANGES review.

30-second setup

Add .github/workflows/codex-guard.yml:

name: Codex Guard
on:
  pull_request:

permissions:
  contents: read
  pull-requests: write
  checks: write

jobs:
  codex-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: Akimiya-z/codex-guard@v1

Then require the Codex Guard status check from Settings → Branches → Require status checks. This repo does exactly that.

Per-repo policy

Override any input from .github/codex-guard.yml on the default branch — policy lives in the repo, and agents can't loosen it from inside their PR:

gate-agents-only: true
fail-on:
  - secrets
  - commits
  - ci
comment-mode: replace
request-changes: true

Local dry-run (CLI)

The same checks run locally before CI:

git diff origin/main > /tmp/patch.diff
npx -y codex-guard --diff /tmp/patch.diff
# or straight against a ref (bare --git scans uncommitted changes):
node src/cli.js --git --commits

Exit codes: 0 = no blocking findings, 1 = blocking findings, 2 = usage error. --json mirrors the findings-json output.

Agent skill

Pack the pre-submit checks as a skill so Codex or Claude Code run them themselves before opening a PR:

bash skills/install.sh      # installs for Codex and Claude Code

The agent runs node src/cli.js --git --commits, fixes findings, and only submits a clean diff. CI then never sees what should have been caught earlier.

Sweep existing PRs

Adopting the gate doesn't have to be retrospective — one workflow_dispatch run inspects every currently-open agent PR and writes a report:

on:
  workflow_dispatch:
jobs:
  sweep:
    runs-on: ubuntu-latest
    steps:
      - uses: Akimiya-z/codex-guard@v1
        with:
          sweep: 'true'

How it compares

Option	Role
Branch protection	The policy; Codex Guard is the check that enforces agent-hygiene rules on a PR
Secret scanners (gitleaks…)	Deep secret detection across history — use in addition
Linters / formatters	Style and static-analysis; we catch workflow issues they don't
AI review bots (CodeRabbit…)	LLM reviews — slow, opinionated, per-review token cost; Codex Guard is deterministic, fast, free, and gate-able without debate

Roadmap

✔ request-changes reviews, in-place comments, config file, JSON output
✔ local CLI, agent skill, sweep mode
✔ npm-ready packaging, protected main
✔ npm published — npx codex-guard works with no install
No AI-review plans — per-token costs contradict the free, deterministic positioning