# AI use cases for Codex Guard (Akimiya-z/codex-guard)

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Use cases: 5 | Page: https://dedupedai.com/use-cases/akimiya-z-codex-guard/

A GitHub Action and CLI that checks AI-generated pull requests for TODO leftovers, leaked secrets, sloppy commit subjects and failing CI before they reach main.

This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL.

- Gate AI-generated PRs before they merge to main: https://dedupedai.com/use-cases/akimiya-z-codex-guard/gate-agent-prs-on-github/
- Preview gate findings on a local diff before pushing: https://dedupedai.com/use-cases/akimiya-z-codex-guard/dry-run-diff-before-push/
- Check a Codex Guard install for config errors: https://dedupedai.com/use-cases/akimiya-z-codex-guard/diagnose-workflow-setup/
- Set a per-repo gate policy agents cannot loosen: https://dedupedai.com/use-cases/akimiya-z-codex-guard/tune-gate-policy-per-repo/
- Scan every open agent PR in one manual run: https://dedupedai.com/use-cases/akimiya-z-codex-guard/sweep-open-agent-prs/

## How to gate AI-generated PRs before they merge to main with Codex Guard

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Install a workflow that scans agent-written PRs for TODOs, secrets, bad commits and red CI.

**Who it is for:** A maintainer whose repo receives pull requests from Codex, Claude Code or Copilot and who wants routine problems caught before human review.

**The problem:** Agent-written PRs often arrive with leftover TODO comments, hardcoded keys, WIP commit subjects and failing CI, which wastes reviewer time.

**The outcome:** Agent PRs get annotated findings and a summary comment automatically, and the Codex Guard status check can block merges once you turn on enforcement.

### Steps

1. Run `npx --yes codex-guard init` from the root of your Git repository.
2. Run `git add .github/workflows/codex-guard.yml`.
3. Run `git commit -m "ci: add Codex Guard"` and push the branch.
4. Open a test pull request from a codex/ branch and check the Codex Guard report. (inferred, check the README)
5. Set `preset: 'balanced'` in the workflow, then add Codex Guard under Settings, Branches, Require status checks.

### Prompt to paste into your agent

```text
In the repository Akimiya-z/codex-guard style Git repo at <repo-path>, run `npx --yes codex-guard init` and then add and commit .github/workflows/codex-guard.yml. Expected output: the workflow file exists and is staged. Verify that the file contains `uses: Akimiya-z/codex-guard@v1`.
```

### Caveat

The installer starts in observe mode, so findings are reported but do not fail the workflow until you choose a stronger preset.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/akimiya-z-codex-guard/gate-agent-prs-on-github/

## How to preview gate findings on a local diff before pushing with Codex Guard

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Run the Codex Guard CLI on a patch file to see the same checks locally before CI.

**Who it is for:** A developer or agent operator who wants to check AI-written changes on their own machine before opening a pull request.

**The problem:** Waiting for CI to report a leftover TODO or a hardcoded key wastes time and a push cycle.

**The outcome:** The same TODO, secret and commit checks run locally on the diff, so problems are fixed before the branch is pushed.

### Steps

1. Write the change to a patch file with `git diff main > /tmp/patch.diff`. (inferred, check the README)
2. Run `npx --yes codex-guard --diff /tmp/patch.diff`. (inferred, check the README)
3. Read each finding and its file and line.
4. Fix the flagged lines, regenerate the patch, and run the command again.

### Prompt to paste into your agent

```text
In the repository at <repo-path>, create /tmp/patch.diff from the diff against main and run `npx --yes codex-guard --diff /tmp/patch.diff`. Expected output: a list of TODO, secret and commit findings, or a clean result. Verify that no finding points to a file you did not change.
```

### Caveat

The README example is a diff file path, so the patch must come from a diff of the same changes you want checked.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/akimiya-z-codex-guard/dry-run-diff-before-push/

## How to check a Codex Guard install for config errors with Codex Guard

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Difficulty: Intermediate | Time: 15 minutes | Basis: From the README

Run the read-only doctor to find workflow, permission and policy mistakes locally.

**Who it is for:** A maintainer who just installed or edited Codex Guard policy and is unsure whether the workflow is correct.

**The problem:** A missing permission or a typo in the policy file can quietly weaken or break the gate.

**The outcome:** A list of checks for the PR trigger, Action step, permissions, preset, policy YAML and fail-on values, with a clear exit code.

### Steps

1. Run `npx --yes codex-guard doctor` from the repository root.
2. Run `npx --yes codex-guard doctor --json` if you need machine-readable output.
3. Fix any configuration errors in the workflow or .github/codex-guard.yml.
4. Run the doctor again until it exits 0.

### Prompt to paste into your agent

```text
In the repository at <repo-path>, run `npx --yes codex-guard doctor --json` and save the output. Expected output: JSON describing each check as a pass, warning or error. Verify that the command exit code is 0 or 1 and that any error names the file and key involved.
```

### Caveat

The doctor only reads local files, so GitHub branch protection and organization policy still need to be checked in repository settings.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/akimiya-z-codex-guard/diagnose-workflow-setup/

## How to set a per-repo gate policy agents cannot loosen with Codex Guard

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Difficulty: Intermediate | Time: 30 minutes | Basis: From the README

Put the policy in .github/codex-guard.yml on the default branch to set blocking rules.

**Who it is for:** A repository owner who wants to choose which findings block merges and does not want agents to change that in their own PRs.

**The problem:** Different repos need different tolerance for TODOs and secret patterns, and per-PR changes should not weaken the rules.

**The outcome:** A policy file on the default branch sets the preset, blocking checks, labels and comment behavior for every matching PR.

### Steps

1. Copy examples/codex-guard.yml from the Codex Guard repository into .github/codex-guard.yml.
2. Set `preset: balanced` and list your agent-labels and secret-exclude-paths.
3. Commit the file to the default branch.
4. Run `npx --yes codex-guard doctor` to check the policy file.

### Prompt to paste into your agent

```text
In the repository at <repo-path>, create .github/codex-guard.yml with `preset: balanced` and `comment-mode: replace`, then run `npx --yes codex-guard doctor`. Expected output: the policy file is accepted with no errors. Verify that the file is on the default branch and not only in a feature branch.
```

### Caveat

The policy file only counts when it is on the default branch, so changes made inside an agent PR do not apply to that PR.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/akimiya-z-codex-guard/tune-gate-policy-per-repo/

## How to scan every open agent PR in one manual run with Codex Guard

Repo: [Akimiya-z/codex-guard](https://github.com/Akimiya-z/codex-guard) | Difficulty: Advanced | Time: 30 minutes | Basis: From the README

Use the sweep input with workflow_dispatch to check all open agent pull requests at once.

**Who it is for:** A maintainer with a backlog of open AI-generated pull requests who wants a single pass over them.

**The problem:** Old agent PRs collect problems over time and are easy to forget until someone reviews them.

**The outcome:** Every open agent PR targeting the chosen base branch gets a Codex Guard report from one manual workflow run.

### Steps

1. Add a workflow_dispatch trigger to .github/workflows/codex-guard.yml. (inferred, check the README)
2. Set the Action input `sweep: true`, and optionally `sweep-label` and `sweep-base`. (inferred, check the README)
3. Run the workflow manually from the Actions tab.
4. Review the reports posted on each open agent PR.

### Prompt to paste into your agent

```text
In the repository at <repo-path>, add a workflow_dispatch trigger and set sweep to true in .github/workflows/codex-guard.yml, then run the workflow manually. Expected output: a report on each open agent PR targeting main. Verify that human-authored PRs without agent markers were not reported.
```

### Caveat

The README says sweep is meant for use with workflow_dispatch, and the exact trigger wiring is not shown there, so check it against the repo docs before relying on it.

Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/

URL: https://dedupedai.com/use-cases/akimiya-z-codex-guard/sweep-open-agent-prs/