Skip to content
Back to search

codex-guard

SkillWorks with CodexGitHub

Quality gate for AI/Codex-generated pull requests: blocks TODO leftovers, leaked secrets, sloppy commits and red CI before they reach main.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Akimiya-z/codex-guard with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Akimiya-z/codex-guard'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/akimiya-z--codex-guard/badge.svg)](/listings/akimiya-z--codex-guard)

HTML

<a href="/listings/akimiya-z--codex-guard"><img src="/api/listings/akimiya-z--codex-guard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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 installer starts in **observe mode**: findings are annotated, but they do not fail the workflow while you tune the policy. Three setup presets keep the rollout explicit:

| Preset | Command | Behavior | | --- | --- | --- | | Observe | `npx --yes codex-guard init` | Report everything without blocking. | | Balanced | `npx --yes codex-guard init --preset balanced` | Block secrets, commit hygiene, and red CI; warn on unfinished markers. | | Strict | `npx --yes codex-guard init --preset strict` | Block every default finding. `--strict` remains an alias. |

Prefer to add it by hand? The generated workflow is:

# Generated by codex-guard init
name: Codex Guard
on:
  pull_request:

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

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

That's it. Codex Guard now reports on matching PRs without blocking them.

> Upgrading an existing workflow? Add `statuses: read` to its `permissions` > block. `checks: write` already includes read access for check runs. Without > status access, Codex Guard reports incomplete CI visibility and returns a > neutral result instead of claiming every check is green.

One-click from the [GitHub Actions Marketplace](https://github.com/marketplace/actions/codex-guard-pr-quality-gate).

Turn on enforcement

After a few representative PRs, choose how strongly to enforce:

- uses: Akimiya-z/codex-guard@v1
  with:
    preset: 'balanced' # or 'strict'

`balanced` warns on unfinished markers while blocking secrets, commit hygiene, and red CI. `strict` blocks every default finding. For a custom mix, use `fail-on` and the individual inputs. Then require the status check under **Settings → Branches → Require status checks → `Codex Guard`**. A blocking finding will prevent the PR from merging until it is resolved (or the PR is marked with an `ignore` label — see "Opting out").

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 527 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🤖 Codex Guard
  2. ![GitHub release (latest by SemVer)](https://img.shields.io/github/v/release/Akimiya-z/codex-guard)
  3. ![GitHub stars](https://img.shields.io/github/stars/Akimiya-z/codex-guard)
  4. ![License](https://img.shields.io/github/license/Akimiya-z/codex-guard)
  5. ![CI](https://github.com/Akimiya-z/codex-guard/actions/workflows/ci.yml/badge.svg)
  6. ![Docs](https://img.shields.io/badge/docs-akimiya--z.github.io%2Fcodex-guard-8b5cf6)
  7. [![Marketplace](https://img.shields.io/badge/GitHub%20Actions%20Marketplace-Codex%20Guard%20PR%20Quality%20Gate-2088FF?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/codex-guard-pr-quality-gate)
  8. [![Awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
  9. **Docs site:** <https://akimiya-z.github.io/codex-guard>
  10. **An automatic quality gate for AI-generated pull requests.** Stop TODO leftovers,
  11. leaked secrets, sloppy commits and red CI from reaching `main` — with zero review
  12. bandwidth spent on the obvious stuff.
  13. Works with **OpenAI Codex** (cloud & CLI), **Claude Code**, **Copilot**, and any
  14. other agent that opens PRs against your repo.
  15. > 🐕 **Dogfooding:** this repo gates its own AI-generated PRs. See a real failing
  16. > example on [PR #6](https://github.com/Akimiya-z/codex-guard/pull/6) and the
  17. > workflow behind it in `.github/workflows/codex-guard.yml`.
  18. ---
  19. ## Why
  20. AI coding agents are great at writing code and terrible at cleaning up after
  21. themselves. In practice, agent-written PRs tend to arrive with the same handful
  22. of problems:
  23. - `// TODO: handle this` comments that were never meant to stay
  24. - Hardcoded API keys and connection strings copied from a chat transcript
  25. - Commit trails like `WIP`, `fix stuff`, `more changes` — squashed versions of
  26. a messy session
  27. - A green-looking PR that actually has failing CI on the head commit
  28. You shouldn't need a human reviewer to catch those every single time. **Codex
  29. Guard checks the boring, deterministic things automatically, and only on PRs
  30. that look AI-generated** — so human attention goes where it matters.
  31. ## How it works
  32. Codex Guard runs on `pull_request`, figures out whether the PR looks
  33. agent-generated (via label, branch prefix, or title), and then:
  34. | Check | What it flags |
  35. | --- | --- |
  36. | 🧹 TODO scan | `TODO` / `FIXME` / `XXX` / `HACK` / `WIP` markers on **added lines only** |
  37. | 🔐 Secret scan | AWS (access + secret keys), GitHub, Google, OpenAI, Anthropic, Slack, Stripe, npm, SendGrid, Telegram, Azure connection strings, JWTs, hardcoded credentials, connection strings (values are redacted in reports) |
  38. | 💬 Commit hygiene | Subjects that don't match conventional commits, empty subjects |
  39. | 🧪 CI status | Failing status checks **or** check runs on the PR head commit |
  40. Each finding is posted as a GitHub **check-run annotation at the exact file and
  41. line**, plus a human-readable summary comment on the PR.
  42. ### Honest content-scan coverage
  43. GitHub sometimes omits the textual patch for binary or very large files. Codex
  44. Guard now distinguishes **no findings** from **not scanned**: every report shows
  45. the number of eligible changed files whose patches were actually inspected. A
  46. missing patch produces a neutral, non-blocking coverage warning with the
  47. affected paths; the JSON and Action outputs carry the same information. The
  48. warning also appears when GitHub's pull-request files API reaches its documented
  49. 3,000-file limit.
  50. The output below comes from a real run on this repo
  51. ([PR #6](https://github.com/Akimiya-z/codex-guard/pull/6)) — a deliberate test
  52. PR from a `codex/` branch that left a TODO, credential-shaped fixtures and two
  53. sloppy commits. Secret-shaped values are redacted here just as they are in
  54. current reports:
  55. ```text
  56. ## 🤖 Codex Guard
  57. ❌ **Checks failed — review the findings before merging.**
  58. | Check | Result |
  59. | --- | --- |
  60. | TODO / FIXME scan | ⚠️ 2 |
  61. | Secret scan | ⚠️ 3 |
  62. | Commit hygiene | ⚠️ 2 |
  63. | CI status | ✅ |
  64. **Unfinished work**
  65. - `scripts/sync.js:4` — `FIXME`: const aws = 'AKIA...MPLE'; // FIXME: move this to a secret store
  66. - `scripts/sync.js:2` — `TODO`: // TODO: wire up real retry with exponential backoff.
  67. **Potential leaked secrets**
  68. - `scripts/sync.js:4` — AWS Access Key ID `AKIA...MPLE`
  69. - `scripts/sync.js:5` — Connection string `post...prod`
  70. - `scripts/sync.js:7` — OpenAI API Key `sk-p...6789`
  71. **Commit hygiene**
  72. - `7c84ae1` — _WIP stuff_ (by Akimiya-z)
  73. - `1affcf8` — _tmp_ (by Akimiya-z)
  74. > Detected as an AI-generated PR (branch prefix "codex/").
  75. ```
  76. ## Quick start
  77. From the root of your Git repository:
  78. ```bash
  79. npx --yes codex-guard init
  80. git add .github/workflows/codex-guard.yml
  81. git commit -m "ci: add Codex Guard"
  82. ```
  83. The installer starts in **observe mode**: findings are annotated, but they do
  84. not fail the workflow while you tune the policy. Three setup presets keep the
  85. rollout explicit:
  86. | Preset | Command | Behavior |
  87. | --- | --- | --- |
  88. | Observe | `npx --yes codex-guard init` | Report everything without blocking. |
  89. | Balanced | `npx --yes codex-guard init --preset balanced` | Block secrets, commit hygiene, and red CI; warn on unfinished markers. |
  90. | Strict | `npx --yes codex-guard init --preset strict` | Block every default finding. `--strict` remains an alias. |
  91. Prefer to add it by hand? The generated workflow is:
  92. ```yaml
  93. # Generated by codex-guard init
  94. name: Codex Guard
  95. on:
  96. pull_request:
  97. permissions:
  98. contents: read
  99. statuses: read
  100. pull-requests: write
  101. checks: write
  102. jobs:
  103. codex-guard:
  104. runs-on: ubuntu-latest
  105. steps:
  106. - uses: Akimiya-z/codex-guard@v1
  107. with:
  108. preset: 'observe'
  109. ```
  110. That's it. Codex Guard now reports on matching PRs without blocking them.
  111. > Upgrading an existing workflow? Add `statuses: read` to its `permissions`
  112. > block. `checks: write` already includes read access for check runs. Without
  113. > status access, Codex Guard reports incomplete CI visibility and returns a
  114. > neutral result instead of claiming every check is green.
  115. One-click from the [GitHub Actions Marketplace](https://github.com/marketplace/actions/codex-guard-pr-quality-gate).
  116. ### Turn on enforcement
  117. After a few representative PRs, choose how strongly to enforce:
  118. ```yaml
  119. - uses: Akimiya-z/codex-guard@v1
  120. with:
  121. preset: 'balanced' # or 'strict'
  122. ```
  123. `balanced` warns on unfinished markers while blocking secrets, commit hygiene,
  124. and red CI. `strict` blocks every default finding. For a custom mix, use
  125. `fail-on` and the individual inputs. Then require the status check under
  126. **Settings → Branches → Require status checks → `Codex Guard`**. A blocking
  127. finding will prevent the PR from merging until it is resolved (or the PR is
  128. marked with an `ignore` label — see "Opting out").
  129. ## Detecting agent PRs
  130. By default Codex Guard **only gates PRs it believes were written by an agent**,
  131. so human-authored PRs are never slowed down:
  132. - **Label** matches one of `codex-generated`, `agentic`, `ai-generated`
  133. - **Branch** starts with `codex/`, `copilot/`, `claude-auto`, `gh-codex/`
  134. - **Title** contains `Generated by Codex`, `Generated by Claude`, `Generated by Copilot`
  135. All of these are configurable — or set `gate-agents-only: false` to gate every PR.
  136. ### Opting out of a specific PR
  137. Add a label named `codex-guard-ignore` (configurable) to a PR and Codex Guard
  138. will pass it without running checks. Useful when a human has already reviewed
  139. and accepted the changes.
  140. ## Inputs
  141. | Input | Default | Description |
  142. | --- | --- | --- |
  143. | `preset` | _(empty)_ | Policy baseline: `observe`, `balanced`, or `strict`. Empty preserves the pre-preset behavior. Repository policy can override it. |
  144. | `github-token` | `${{ github.token }}` | Token with write access to checks and PRs. |
  145. | `gate-agents-only` | `true` | Only gate PRs detected as agent-generated. |
  146. | `agent-labels` | `codex-generated,agentic,ai-generated` | Labels marking an agent PR. |
  147. | `agent-branch-prefixes` | `codex/,copilot/,claude-auto,gh-codex/` | Branch prefixes marking an agent PR. |
  148. | `agent-keywords` | `Generated by Codex,Generated by Claude,Generated by Copilot` | Title keywords marking an agent PR. |
  149. | `ignore-label` | `codex-guard-ignore` | PR label that skips all checks. |
  150. | `check-todos` | `true` | Scan added lines for unfinished-work markers. |
  151. | `todo-patterns` | `TODO,FIXME,XXX,HACK,WIP` | Markers to flag. |
  152. | `todo-blocking` | `true` | Fail on TODO findings (`false` = warn only). |
  153. | `check-secrets` | `true` | Scan added lines for hardcoded secrets. |
  154. | `secret-exclude-paths` | _(empty)_ | File path substrings to skip (e.g. `README,test/fixtures`). |
  155. | `check-commits` | `true` | Validate commit subjects. |
  156. | `commit-pattern` | conventional commit regex | Regex subjects must match. |
  157. | `check-ci` | `true` | Fail on failing CI for the head commit. |
  158. | `ignore-check-run-names` | _(empty)_ | Check/context names to ignore when assessing CI. |
  159. | `post-comment` | `true` | Post a report comment on failures. |
  160. | `comment-mode` | `replace` | `replace` updates the previous report in place (one comment per PR), `append` posts a new one each run, `none` never posts. |
  161. | `request-changes` | `false` | Also submit a formal `REQUEST_CHANGES` review on blocking findings (opt-in; needs `pull-requests: write`). |
  162. | `notify-users` | _(empty)_ | Comma-separated usernames to @-mention in the report comment on blocking findings. |
  163. | `soft-fail` | `false` | Report findings with a neutral check-run but never fail the workflow. |
  164. | `config-path` | `.github/codex-guard.yml` | Optional per-repo policy file (on the default branch) overriding workflow inputs. |
  165. | `fail-on` | _(empty)_ | Comma-separated blocking checks: `todos,secrets,commits,ci`. Empty = legacy behavior; a subset makes excluded checks non-blocking. |
  166. | `sweep` | `false` | Scan every open agent PR instead of a single one (use with `workflow_dispatch`). |
  167. | `sweep-label` | _(empty)_ | Only sweep PRs carrying this label. |
  168. | `sweep-base` | `main` | Only sweep PRs targeting this base branch. |
  169. ### CI results are never guessed
  170. Codex Guard reads both commit statuses and check runs, follows every results
  171. page up to GitHub's 3,000-result safety cap, and treats every completed
  172. non-success conclusion as a failure. Pending checks produce a neutral result,
  173. not a premature green check. If one GitHub CI API is unavailable, the report is
  174. neutral and explicitly says visibility is incomplete; if both are unavailable,
  175. the CI check fails closed. Previous Codex Guard check runs are ignored so a
  176. rerun cannot inherit its own old failure.
  177. ## Configuration file
  178. **AGENTS.md-aware:** if the repository's `AGENTS.md` or `CLAUDE.md` states a
  179. commit convention as a backticked regex (e.g. "commits must match
  180. `^JIRA-[0-9]+: .+$`"), Codex Guard applies it as a **last-resort default** when
  181. no `commit-pattern` input or config key is set — action and CLI both.
  182. Every input above can be overridden per-repo with a `.github/codex-guard.yml`
  183. file on the default branch — so agents can't just loosen the policy in their PR.
  184. Unknown keys are ignored (typo tolerant).
  185. ```yaml
  186. # .github/codex-guard.yml
  187. preset: balanced
  188. gate-agents-only: true
  189. agent-labels:
  190. - codex-generated
  191. - agentic
  192. todo-patterns:
  193. - TODO
  194. - FIXME
  195. - XXX
  196. secret-exclude-paths:
  197. - README.md
  198. - docs/
  199. comment-mode: replace
  200. request-changes: true
  201. ```
  202. A copy-paste template lives at [`examples/codex-guard.yml`](examples/codex-guard.yml).
  203. Policy resolution is deterministic: the workflow `preset` supplies a baseline,
  204. the repository `preset` replaces that baseline, and individual repository keys
  205. win last. This keeps existing workflows compatible because an empty workflow
  206. `preset` retains the legacy defaults.
  207. ### Diagnose an installation
  208. Run the read-only local doctor after installing or changing policy:
  209. ```bash
  210. npx --yes codex-guard doctor
  211. npx --yes codex-guard doctor --json # machine-readable output
  212. ```
  213. It checks the pull-request trigger, Action step, effective workflow/job
  214. permissions, setup preset, policy YAML, unknown keys, boolean values,
  215. `comment-mode`, and `fail-on`. It exits `1` for configuration errors and `0`
  216. when only warnings or passes remain. This is a local-file diagnostic; GitHub
  217. branch protection and organization policy still live in repository settings.
  218. ## Local dry-run (CLI)
  219. The CLI installs the workflow and previews the same checks locally before CI —
  220. no token or waiting:
  221. ```bash
  222. # install the GitHub workflow (safe observe mode by default)
  223. npx --yes codex-guard init
  224. # scan a diff from npm — no install needed (v1.7.0+)
  225. npx --yes codex-guard --diff <(git diff origin/main)
  226. # from this repo's source
  227. git diff origin/main > /tmp/patch.diff
  228. node src/cli.js --diff /tmp/patch.diff
  229. # or straight against a ref (bare `--git` scans tracked + untracked changes)
  230. npx --yes codex-guard --git --commits
  231. node src/cli.js --git origin/main --commits
  232. ```
  233. PowerShell does not support Bash process substitution (`<(...)`). Save the
  234. diff to a temporary UTF-8 file instead:
  235. ```powershell
  236. $patch = New-TemporaryFile
  237. try {
  238. git diff origin/main | Set-Content -LiteralPath $patch -Encoding utf8
  239. npx --yes codex-guard --diff $patch
  240. } finally {
  241. Remove-Item -LiteralPath $patch
  242. }
  243. ```
  244. Exit codes: `0` = no blocking findings, `1` = blocking findings, `2` = usage
  245. error. `--json` prints the raw report (same shape as the `findings-json`
  246. output) for scripts. In `--git` mode the CLI automatically loads
  247. `.github/codex-guard.yml`, so local content checks use the same preset,
  248. patterns, exclusions, and blocking rules as the Action. Use `--preset` or
  249. individual flags for an explicit local override, `--config <path>` for another
  250. policy file, or `--no-config` to bypass repository policy. Explicit CLI flags
  251. win over the loaded file. Commit hygiene is checked only when `--commits` is
  252. passed. Git-ignored files stay ignored; ordinary untracked files are treated as
  253. all-added patches, so a new file is scanned before its first `git add`. Binary
  254. or untracked files larger than 8 MiB are listed explicitly as unscanned instead
  255. of being silently treated as clean.
  256. ## Agent skill (pre-submit self-check)
  257. Same checks, one level further up: packed as a **skill**, so Codex or Claude
  258. Code run them _themselves_ before opening a PR — the CI gate then never sees a
  259. dirty diff that the agent didn't already spot locally. This repo ships the
  260. skill in `skills/codex-guard/SKILL.md`; install it with:
  261. ```bash
  262. bash skills/install.sh # installs for Codex and Claude Code
  263. # or copy skills/codex-guard/ into ~/.codex/skills/ or ~/.claude/skills/
  264. ```
  265. The skill tells the agent to run `node src/cli.js --git --commits` before
  266. submitting, fix TODO/secret/commit findings, and only open the PR once the
  267. checks pass (or the exception is documented in the description).
  268. ## Codex plugin
  269. The same skill is packaged as an official **Codex plugin** (skill-only form,
  270. schema follows `openai/plugins`): `plugins/codex-guard/.codex-plugin/plugin.json`
  271. plus a marketplace manifest at `.agents/plugins/marketplace.json`. Codex users
  272. can add this repository as a plugin marketplace from the Codex app or CLI —
  273. install steps are in OpenAI's plugin docs:
  274. <https://developers.openai.com/codex/plugins/build>.
  275. ```text
  276. plugins/codex-guard/.codex-plugin/plugin.json
  277. plugins/codex-guard/skills/codex-guard/SKILL.md
  278. .agents/plugins/marketplace.json
  279. ```
  280. Once installed, Codex runs the pre-submit checks itself before opening or
  281. updating a PR — same behavior as the standalone skill, one packaging step
  282. closer to discoverable on GitHub (see the `codex-plugin` topic).
  283. ## DeepSeek Harness plugin (dsh)
  284. A DSH bundle lives in `dsh/`: it declares a `dsh.bundle` manifest and registers
  285. a `codex_guard` **tool** that DeepSeek Harness agents can call to pre-flight an
  286. agent-authored diff before it becomes a PR.
  287. ```text
  288. dsh/
  289. ├── package.json # dsh.bundle manifest (name: dsh-codex-guard)
  290. ├── cordis.patch.yml # the layer a profile applies
  291. └── index.js # registers the codex_guard tool (dsh-tools API)
  292. ```
  293. The tool shells out to the published CLI (`npx --yes codex-guard --git`) in the
  294. current working directory, so it gets the same deterministic report the CI gate
  295. uses. Node API compatibility is **tested against the real `@deepseek-ai/dsh-tools`
  296. registry packages** (see `test/dsh.test.js`), including an end-to-end run in a
  297. throwaway git repo.
  298. ## Outputs
  299. | Output | Description |
  300. | --- | --- |
  301. | `policy-preset` | Selected policy baseline: `observe`, `balanced`, `strict`, or `custom`. Individual policy keys may still override it. |
  302. | `result` | `pass`, `fail`, or `skipped`. |
  303. | `detected-agent` | `true` / `false` — whether the PR looked agent-generated. |
  304. | `failed-checks` | Comma-separated list of failed checks (`todos,secrets,commits,ci`). |
  305. | `todo-count` / `secret-count` / `commit-count` | Findings per category. |
  306. | `ci-failure-count` | Number of failing CI checks. |
  307. | `content-scan-coverage` | Text patches scanned / eligible files, such as `12/13`, or `disabled`. |
  308. | `unscanned-file-count` | Eligible files GitHub did not provide a textual patch for. |
  309. | `findings-json` | JSON of the full report — pipe it into later steps to gate more or build dashboards. |
  310. | `sweep-scanned` / `sweep-failed` | Sweep mode: agent PRs inspected / with blocking findings. |
  311. | `sweep-report` / `sweep-json` | Sweep mode: markdown report (also in the run summary) / per-PR JSON. |
  312. ## Sweeping existing PRs
  313. Adopting Codex Guard doesn't have to be retrospective — run a **sweep** to
  314. inspect every currently-open agent-generated PR in one go. Add a `schedule`
  315. trigger (the example ships with a weekly Monday run) for a zero-touch weekly
  316. agent-PR health check:
  317. ```yaml
  318. on:
  319. workflow_dispatch:
  320. # … uses: Akimiya-z/codex-guard@v1 with: { sweep: 'true' }
  321. ```
  322. The report is written to the run summary and `sweep-report` output (per-PR
  323. numbers in `sweep-json`). No per-PR comments or check-runs are posted.
  324. Use `sweep-label` to limit the run to PRs carrying a particular label.
  325. Copy-paste at [`examples/sweep.yml`](examples/sweep.yml).
  326. ## Examples
  327. **Gate everything, and skip secrets scanning on docs:**
  328. ```yaml
  329. steps:
  330. - uses: Akimiya-z/codex-guard@v1
  331. with:
  332. gate-agents-only: 'false'
  333. secret-exclude-paths: 'README.md,docs/'
  334. ```
  335. **Observe first, enforce later:**
  336. ```yaml
  337. steps:
  338. - uses: Akimiya-z/codex-guard@v1
  339. with:
  340. preset: 'observe'
  341. ```
  342. **Integrate with a tool that adds the agent label automatically:**
  343. If your agent has a GitHub App or a bot that labels PRs, current Codex Guard will
  344. respect whatever label you configure — and fails open (passes) when a PR has no
  345. signal at all.
  346. **Keep gating agent PRs from forks:**
  347. Use `pull_request_target` so the check runs with your repo's write token. The
  348. action reads the fork PR's files, commits and head SHA from the event payload —
  349. no extra config. Copy-paste at [`examples/forks.yml`](examples/forks.yml).
  350. ## How it compares
  351. | Tool | What it does | Why you'd also want Codex Guard |
  352. | --- | --- | --- |
  353. | **Branch protection** | Blocks merges without required reviews/checks | It's the _policy_; Codex Guard is the _check_ that enforces agent-hygiene rules on a PR. |
  354. | **Secret scanners** (gitleaks, TruffleHog) | Deep secret detection across history | Use **in addition** — ours is a cheap diff-scoped regex pass, not a replacement. |
  355. | **Linters / formatters** | Style and static-analysis gates | We catch _workflow_ issues agents leave behind (TODO, secrets, commit hygiene, red CI) that linters don't. |
  356. | **AI review bots** (CodeRabbit, etc.) | LLM-powered PR review | Great — and slow/opinionated with per-review token cost. Codex Guard is deterministic, fast, **free to run in CI**, and gate-able without debate. |
  357. | **Agent self-review hooks** | Agent checks its own output | Defaults fail; a neutral deterministic gate doesn't nod along. |
  358. ## Community
  359. - **Ask & discuss** — questions, setups, and roadmap voting live in
  360. [GitHub Discussions](https://github.com/Akimiya-z/codex-guard/discussions);
  361. bug reports and feature requests go through the
  362. [issue templates](https://github.com/Akimiya-z/codex-guard/issues/new/choose).
  363. - **Good first issues** are tagged [`good first issue`](https://github.com/Akimiya-z/codex-guard/labels/good%20first%20issue)
  364. and `help wanted` — the contribution guide is in
  365. [CONTRIBUTING.md](CONTRIBUTING.md).
  366. - **Roadmap is feedback-driven**: the fastest way to influence the next release
  367. is to open a feature request and vote on it in Discussions.
  368. - Every external contribution gets called out in the release notes. Thank you —
  369. this project lives on its users' feedback.
  370. ## Development
  371. ```bash
  372. npm install
  373. npm test # node:test — no framework required
  374. npm run check # syntax-check every source file
  375. npm run build # rebuild the checked-in Action bundle
  376. ```
  377. Consult `CONTRIBUTING.md` before opening a PR — it covers the release process
  378. (rebuild `dist/`, tag `v1.x`). See [`CHANGELOG.md`](./CHANGELOG.md) for
  379. release history. Copy-paste workflows live in `examples/`, and `docs/` explains
  380. how to record the demo GIF and smoke-test locally.
  381. ## Limitations
  382. - Secret detection is **regex-based on purpose** — it catches the obvious
  383. mistakes cheaply, but it is not a replacement for a real secret scanner
  384. (use [gitleaks](https://github.com/gitleaks/gitleaks) or
  385. [zizmor](https://github.com/woodruffw/zizmor) in addition).
  386. - The TODO scan only sees lines **added by this PR** — it won't nag you about
  387. pre-existing comments.
  388. - GitHub may omit textual patches for binary or very large files. Those files
  389. cannot be content-scanned. Codex Guard reports their paths and uses a neutral
  390. check conclusion instead of silently claiming full coverage, but a
  391. repository-wide secret scanner should remain the authoritative control.
  392. - GitHub's [pull-request files endpoint](https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files)
  393. returns at most 3,000 files. Reaching that limit is reported as incomplete
  394. coverage because additional files may be absent.
  395. - Commit statuses and check runs also have a conservative 3,000-result safety
  396. cap per API. Reaching it is reported as incomplete CI visibility rather than
  397. silently ignoring later results.
  398. - The local CLI scans ordinary untracked files, but reports binary files and
  399. untracked files larger than 8 MiB as unscanned. Git-ignored files are omitted
  400. by design.
  401. - Agent detection is intentionally heuristic. Set `gate-agents-only: false`
  402. when coverage matters more than distinguishing human and agent PRs.
  403. - Runs on `pull_request` events; for fork contributions use
  404. `pull_request_target` (see [`examples/forks.yml`](examples/forks.yml)) and
  405. supply a token with the right scope.
  406. ## Roadmap
  407. - [x] Auto-`request changes` instead of only failing the check (opt-in)
  408. - [x] Replace/update the report comment in place across runs
  409. - [x] Config file support (`.github/codex-guard.yml`) for per-repo policy
  410. - [x] Agent skill (SKILL.md) for pre-submit self-checks
  411. - [x] `workflow_dispatch` sweep of existing agent PRs
  412. - [x] Published to npm (`npx codex-guard`)
  413. - [x] One-command observe-mode installer (`npx codex-guard init`)
  414. - [x] Observe/balanced/strict installer presets and local setup doctor
  415. - [x] Local scanning of non-ignored, untracked files
  416. - [x] Shared Action/CLI presets with automatic local repository policy loading
  417. _Dropped by design: AI whole-PR summary gates — per-token LLM costs contradict
  418. the project's free, deterministic positioning. Codex Guard stays zero-cost._
  419. ## License
  420. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.