🤖 Codex Guard

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:

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

Run this from the root of your Git repository:

npx --yes codex-guard init
git add .github/workflows/codex-guard.yml
git commit -m "ci: add Codex Guard"

The generated workflow starts in observe mode: it annotates findings without blocking merges while you tune the policy. Use --preset balanced to block secrets, commits, and red CI while warning on unfinished markers, or --preset strict to enforce every default finding.

Existing workflows upgrading to this release should add statuses: read to their permissions block so both GitHub CI result APIs remain visible.

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:

preset: balanced
gate-agents-only: true
comment-mode: replace
request-changes: true

The workflow preset is the baseline, the repository preset replaces it, and individual repository keys win last.

Run npx --yes codex-guard doctor to validate the trigger, permissions, Action step, preset, policy keys, and policy values locally.

Local dry-run (CLI)

The same CLI also runs checks locally before CI:

git diff origin/main > /tmp/patch.diff
npx --yes codex-guard --diff /tmp/patch.diff
# or straight against a ref (bare --git includes untracked files):
node src/cli.js --git --commits

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

Using PowerShell? Bash process substitution is unavailable there; use the temporary-file recipe in the README.

--git automatically loads .github/codex-guard.yml. Explicit CLI flags win; use --config <path> for another policy or --no-config to bypass it.

Git-ignored files remain ignored. Binary and untracked files larger than 8 MiB are listed as unscanned instead of being silently treated as clean.

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'

Richer outputs

Beyond result and failed-checks, every run exposes policy-preset (which baseline applied), content-scan-coverage / unscanned-file-count (how much of the PR was scannable), findings-json (structured report), and the sweep outputs (sweep-report, …).

How it compares

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
• ✔ one-command safe installer — npx codex-guard init
• ✔ explicit content-scan coverage and missing-patch warnings
• ✔ fail-closed, paginated CI visibility and injection-safe reports
• ✔ installer presets, setup doctor, and untracked-file local scans
• ✔ shared Action/CLI presets and automatic local policy loading
• No AI-review plans — per-token costs contradict the free, deterministic positioning