Codex ProofKit is a small, offline plugin for proof-carrying open-source maintenance. It helps Codex and human maintainers distinguish “the agent says it is done” from three checkable facts:
- agent-facing repository configuration is structurally sane;
- tests or reviews produced concrete evidence files;
- delivered artifacts still match a SHA-256 receipt.
It uses the Python standard library, makes no network requests, and never executes command text supplied to a receipt.
Current release: 0.3.0. See CHANGELOG.md for the public maintenance history.
Add the gate after checkout. The action audits the exact Git-tracked release surface, writes a Markdown Job Summary, and creates machine-readable proof files under .codex-proof/:
permissions:
contents: read
steps:
- uses: actions/checkout@v5
- id: proofkit
uses: benzzy1287/codex-proofkit@v0.3.0The default gate fails on errors and warnings. Set strict: "false" to allow warnings, or receipt: "false" to skip the full Git-tracked receipt. Outputs include status, evidence_dir, audit_path, summary_path, and receipt_path.
ProofKit does not upload anything implicitly. To make only the generated proof files downloadable from a workflow run, add this explicit step:
- name: Upload ProofKit evidence
if: ${{ always() }}
uses: actions/upload-artifact@v4
with:
name: codex-proofkit-evidence
path: ${{ steps.proofkit.outputs.evidence_dir }}
include-hidden-files: true
if-no-files-found: errorThe composite action requires Bash, Git, and Python 3, and is tested on GitHub-hosted Ubuntu runners.
From any Git repository, run ProofKit directly from a clone or installed plugin:
python3 /path/to/codex-proofkit/skills/prove-maintainer-work/scripts/proofkit.py \
audit . --git-tracked --strict
--git-tracked selects the file set from Git's index and scans those files in the working tree, so an unrelated untracked note cannot create a false positive. In CI's clean checkout this is the exact release surface. --strict makes every warning fail the gate. A clean run exits 0; a privacy or configuration finding exits 1.
The audit command checks:
- AGENTS.md presence and byte budgets;
- SKILL.md frontmatter, folder naming, and duplicate skill names;
- Codex plugin manifest identity and semantic versioning;
- likely credentials, organization IDs, private keys, non-example email addresses, and hard-coded personal home paths.
The receipt command hashes artifact and evidence files, records the current Git commit when available, and writes a repository-relative JSON receipt. The verify command fails if a recorded file is missing or changed.
Run the tests:
python3 -m unittest discover -s tests -v
Audit the working tree during development:
python3 skills/prove-maintainer-work/scripts/proofkit.py audit .
Audit the Git-tracked release file set in CI or before publishing (stage newly added files first):
git add <intended-files>
python3 skills/prove-maintainer-work/scripts/proofkit.py audit . \
--git-tracked --strict
Create a receipt after running the real project checks:
mkdir -p evidence
python3 -m unittest discover -s tests -v > evidence/tests.log 2>&1
python3 skills/prove-maintainer-work/scripts/proofkit.py receipt . \
--artifact skills \
--artifact README.md \
--evidence evidence/tests.log \
--command "python3 -m unittest discover -s tests -v"
Or hash the complete Git-tracked release surface:
python3 skills/prove-maintainer-work/scripts/proofkit.py receipt . \
--git-tracked \
--command "python3 -m unittest discover -s tests -v"
Write JSON and Markdown audit outputs for another CI system:
python3 skills/prove-maintainer-work/scripts/proofkit.py audit . \
--git-tracked --strict \
--json-out .codex-proof/audit.json \
--summary-out .codex-proof/summary.md
Verify it:
python3 skills/prove-maintainer-work/scripts/proofkit.py verify \
.codex-proof/receipt.json --root .
- audit normally returns 1 for errors;
--strictalso returns 1 for warnings; - verify returns 1 for missing or changed files;
- invalid usage, malformed receipts, or paths outside the repository return 2.
Hash verification proves file integrity. It does not prove that tests were meaningful, that a review was correct, or that a release should be published.
The repository includes a .codex-plugin/plugin.json manifest and the prove-maintainer-work skill. OpenAI's current documentation describes plugins as the distributable package for reusable skills and optional integrations:
- https://developers.openai.com/plugins/build/plugins
- https://learn.chatgpt.com/docs/build-skills
- https://learn.chatgpt.com/docs/plugins
The ProofKit CLI and composite action are local-only. They have no telemetry, credentials, connector, paid service, network call, or implicit upload path. An optional workflow step can explicitly upload only generated proof files. ProofKit rejects proof inputs outside the repository and rejects symlinks to avoid binding a receipt to unexpected files. Findings name the file and risk class but do not echo matched email addresses, usernames, or secret values.
Report vulnerabilities privately as described in SECURITY.md. Do not paste live credentials into an issue.
Tried ProofKit on a public or synthetic repository? Share a short maintainer feedback report. Do not include private code, logs, credentials, email addresses, organization IDs, or account details.
MIT licensed. Codex is a trademark of OpenAI. This independent project is not affiliated with or endorsed by OpenAI.
Chinese documentation: README.zh-CN.md