🤖 Codex Guard

An automatic quality gate for AI-generated pull requests. Stop TODO leftovers,
leaked secrets, sloppy commits and red CI from reaching main — with zero review
bandwidth spent on the obvious stuff.

Works with OpenAI Codex (cloud & CLI), Claude Code, Copilot, and any
other agent that opens PRs against your repo.

🐕 Dogfooding: this repo gates its own AI-generated PRs. See a real failing
example on PR #6 and the
workflow behind it in .github/workflows/codex-guard.yml.

Why

AI coding agents are great at writing code and terrible at cleaning up after
themselves. In practice, agent-written PRs tend to arrive with the same handful
of problems:

• // TODO: handle this comments that were never meant to stay
• Hardcoded API keys and connection strings copied from a chat transcript
• Commit trails like WIP, fix stuff, more changes — squashed versions of
  a messy session
• A green-looking PR that actually has failing CI on the head commit

You shouldn't need a human reviewer to catch those every single time. Codex
Guard checks the boring, deterministic things automatically, and only on PRs
that look AI-generated — so human attention goes where it matters.

How it works

Codex Guard runs on pull_request, figures out whether the PR looks
agent-generated (via label, branch prefix, or title), and then:

Each finding is posted as a GitHub check-run annotation at the exact file and
line, plus a human-readable summary comment on the PR.

The output below is verbatim from a real run on this repo
(PR #6) — an open PR from a
codex/ branch that left a TODO, a hardcoded AWS key, a live connection string
and two sloppy commits:

## 🤖 Codex Guard

❌ **Checks failed — review the findings before merging.**

| Check | Result |
| --- | --- |
| TODO / FIXME scan | ⚠️ 2 |
| Secret scan | ⚠️ 3 |
| Commit hygiene | ⚠️ 2 |
| CI status | ✅ |

**Unfinished work**
- `scripts/sync.js:4` — `FIXME`: const aws = 'AKIAIOSFODNN7EXAMPLE'; // FIXME: move this to a secret store
- `scripts/sync.js:2` — `TODO`: // TODO: wire up real retry with exponential backoff.
**Potential leaked secrets**
- `scripts/sync.js:4` — AWS Access Key ID `AKIA...MPLE`
- `scripts/sync.js:5` — Connection string `post...prod`
- `scripts/sync.js:7` — OpenAI API Key `sk-p...6789`
**Commit hygiene**
- `7c84ae1` — _WIP stuff_ (by Akimiya-z)
- `1affcf8` — _tmp_ (by Akimiya-z)

> Detected as an AI-generated PR (branch prefix "codex/").

Quick start

Add a workflow file, e.g. .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

That's it. The PR fails the required status check until the findings are
resolved (or the PR is marked with an ignore label — see "Opting out").

Block merges on it like any other required check: Settings → Branches →
Require status checks → Codex Guard.

Detecting agent PRs

By default Codex Guard only gates PRs it believes were written by an agent,
so human-authored PRs are never slowed down:

• Label matches one of codex-generated, agentic, ai-generated
• Branch starts with codex/, claude-auto, gh-codex/
• Title contains Generated by Codex, Generated by Claude, Generated by Copilot

All of these are configurable — or set gate-agents-only: false to gate every PR.

Opting out of a specific PR

Add a label named codex-guard-ignore (configurable) to a PR and Codex Guard
will pass it without running checks. Useful when a human has already reviewed
and accepted the changes.

Inputs

Configuration file

Every input above can be overridden per-repo with a .github/codex-guard.yml
file on the default branch — so agents can't just loosen the policy in their PR.
Unknown keys are ignored (typo tolerant).

# .github/codex-guard.yml
gate-agents-only: true
agent-labels:
  - codex-generated
  - agentic
todo-patterns:
  - TODO
  - FIXME
  - XXX
secret-exclude-paths:
  - README.md
  - docs/
# Only these checks block merges; TODOs below fail the run, not the merge.
fail-on:
  - secrets
  - commits
  - ci
comment-mode: replace
request-changes: true

A copy-paste template lives at examples/codex-guard.yml.

Local dry-run (CLI)

Preview the same checks locally before CI — no repo, no token, no waiting.
Point it at a unified diff, get the identical findings and blocking rules:

# from a file (e.g. generated by git diff)
git diff origin/main > /tmp/patch.diff
node src/cli.js --diff /tmp/patch.diff

# or straight against a ref (bare `--git` scans uncommitted changes)
node src/cli.js --git --commits
node src/cli.js --git origin/main --commits
node src/cli.js --git HEAD~1 --patterns TODO,FIXME --exclude docs/

Exit codes: 0 = no blocking findings, 1 = blocking findings, 2 = usage
error. --json prints the raw report (same shape as the findings-json
output) for scripts; --warn-todos and --fail-on todos,secrets,commits
mirror the action's blocking rules. Commit hygiene is checked only in --git
mode when you pass --commits.

Outputs

Examples

Gate everything, and skip secrets scanning on docs:

steps:
  - uses: Akimiya-z/codex-guard@v1
    with:
      gate-agents-only: 'false'
      secret-exclude-paths: 'README.md,docs/'

Observe first, enforce later:

steps:
  - uses: Akimiya-z/codex-guard@v1
    with:
      soft-fail: 'true'

Integrate with a tool that adds the agent label automatically:

If your agent has a GitHub App or a bot that labels PRs, current Codex Guard will
respect whatever label you configure — and fails open (passes) when a PR has no
signal at all.

Keep gating agent PRs from forks:

Use pull_request_target so the check runs with your repo's write token. The
action reads the fork PR's files, commits and head SHA from the event payload —
no extra config. Copy-paste at examples/forks.yml.

How it compares

Development

npm install
npm test          # node:test — no framework required
npm run check     # syntax-check every source file

Consult CONTRIBUTING.md before opening a PR — it covers the release process
(commit node_modules, tag v1.x). See CHANGELOG.md for
release history. Copy-paste workflows live in examples/, and docs/ explains
how to record the demo GIF and smoke-test locally.

Limitations

• Secret detection is regex-based on purpose — it catches the obvious
  mistakes cheaply, but it is not a replacement for a real secret scanner
  (use gitleaks or
  zizmor in addition).
• The TODO scan only sees lines added by this PR — it won't nag you about
  pre-existing comments.
• Runs on pull_request events; for fork contributions use
  pull_request_target (see examples/forks.yml) and
  supply a token with the right scope.

Roadmap

• Auto-request changes instead of only failing the check (opt-in)
• Replace/update the report comment in place across runs
• Config file support (.github/codex-guard.yml) for per-repo policy
• Summarize the whole PR in one AI pass and gate on the review verdict
• Support base-branch comparison for workflow_dispatch review sweeps

License

MIT