Aident AI
How to Run the Codex Security CLI Before You Commit
To scan local changes before you commit, run a Codex Security dry run first, then scan the Git working tree against HEAD with results stored in a private directory outside the repository. Review both report.md and coverage.json. A clean finding count is not enough if coverage is partial or unknown.
The shortest safe sequence on macOS or Linux is:
The CLI is in beta and requires Codex Security access. Only scan repositories you own or have permission to assess.
Prerequisites
OpenAI's current package requires one of these Node.js versions:
Node.js 22.13.0 or later in the Node 22 line;
Node.js 24;
Node.js 26.
Running a scan or exporting findings also requires Python 3.10 or later. You also need a Git repository, access to Codex Security, and a writable private output directory outside the checkout.
Check the environment before signing in:
Expected result: Node and Python meet the supported versions, Git prints the current worktree root, and the CLI prints its version and scan options. If Git prints a different root than you expected, change to that directory before using --working-tree or --diff.
Step 1: Create a Private Results Directory
Codex Security results can contain source excerpts and vulnerability details. Keep them outside the repository and restrict access.
On macOS or Linux:
On Windows PowerShell:
Expected result: the command prints a new directory outside the repository. Do not point --output-dir at a tracked folder. On macOS and Linux, an existing output directory must be private to the current user.
Step 2: Validate the Scan Without Spending or Loading Credentials
Run the working-tree scan with --dry-run:
The dry run checks the repository, selected scope, output directory, and isolated Codex configuration. OpenAI documents that it does not load credentials, start Codex, or probe the plugin's Python interpreter.
Expected result: the CLI accepts the repository root, HEAD, and output location without starting a scan. Fix path, revision, or permission errors now. Do not respond to a bad output path by making the whole repository world-writable.
Step 3: Sign In Explicitly
For a local interactive scan, sign in with ChatGPT:
For a headless machine, use device authentication:
For CI, use OPENAI_API_KEY or CODEX_API_KEY from the CI secret manager. Do not put the key in a command, repository file, or scan artifact.
If both a stored ChatGPT login and an environment API key exist, choose the intended identity:
Expected result: login status identifies a usable local sign-in. If access is denied, confirm that the account has Codex Security access and complete any Trusted Access verification requested by OpenAI.
Step 4: Scan Staged and Unstaged Changes
Run the real scan from the Git worktree root:
--working-tree --base HEAD reviews staged and unstaged changes against the current commit. The CLI is report-only by default. --max-cost 5 stops when the estimated model cost exceeds five US dollars, although requests already in progress can finish above that estimate.
Expected result: stderr ends with a finding count, severity breakdown, coverage state, elapsed time, result directory, and next step. The result directory contains:
Open report.md for the readable review. Then inspect coverage.json for excluded surfaces, deferred work, and open questions. Coverage can be complete, partial, or unknown.
Step 5: Interpret Exit Codes Correctly
Codex Security uses these important exit codes:
Exit | Meaning | What to do |
|---|---|---|
| The scan completed with complete coverage and passed its severity policy | Review the report and coverage before committing |
| A completed scan found an issue at or above | Triage the finding and rerun the relevant scope |
| Input, runtime, or export failed, or coverage is incomplete | Read the error and |
| The user interrupted with Ctrl-C | Keep partial results only as incomplete evidence |
| SIGTERM stopped the scan | Investigate the termination and rerun |
Without --fail-on-severity, findings do not automatically turn the scan into a blocking policy. Add a threshold only when the team is ready to enforce it:
Fetch origin/main first so the selected base revision exists locally.
Step 6: Validate a Finding After a Fix
A later scan that omits a finding does not by itself prove the vulnerability is fixed. Use the bundled validator against the completed findings document:
Expected result: validation directly rechecks the candidate finding. Keep the original report, the code change, and the validation result together for review.
Optional: Install the Pre-Commit Check
After the manual workflow is understood, install the supported hook:
OpenAI says the hook scans staged and unstaged changes before each commit, blocks high-severity findings and scan errors, and does not replace an existing pre-commit script. Inspect the repository's hook setup before enabling it for a team.
Common Failure Modes
Symptom | Likely boundary | Safe response |
|---|---|---|
Node or Python version error | Unsupported local runtime | Upgrade the owning runtime, then repeat the version checks |
Access denied after login | Account lacks access or Trusted Access is incomplete | Confirm entitlement instead of changing repository permissions |
Output directory rejected | Directory is inside the worktree, nonempty, or not private | Create a fresh private directory outside the repository |
| The base ref was not fetched | Fetch the exact base and rerun from the worktree root |
Exit | Coverage is partial or the runtime failed | Read |
Authentication prompt is surprising | ChatGPT login and API key are both available | Pass |
Findings seem unrelated to the changed code | Scope or architecture context is too broad | Use |
Why This Order Works
The dry run isolates local path and configuration problems before authentication or model work begins. A private output directory keeps sensitive findings out of Git. Working-tree scope matches the pre-commit question, while the cost limit bounds the first attempt. Finally, reviewing coverage separately from findings prevents a partial scan from looking clean.
This follows the same practical structure that made Aident's Ollama networking guide useful: state the exact task, give reproducible commands, show expected results, name look-alike failures, and explain why the boundary matters. For broader review discipline, see how to verify an agent's tests and how to audit an agent skill before installation.
Verify One Read-Only GitHub Action With Aident Loadout
Codex Security scans the code. Aident Loadout can separately verify that your coding agent can inspect a connected GitHub surface without receiving a pasted provider token.
Install or update Aident Loadout with this prompt:
Then run:
Inspect the selected Action before any execution:
Use Aident Loadout to inspect one live GitHub Action schema. Measure success as one current schema inspected, zero provider secrets pasted, and zero repository writes.
Sources
Codex Security open-source repository, OpenAI, accessed July 29, 2026
Codex Security CLI quickstart, OpenAI, accessed July 29, 2026
Codex Security CLI reference, OpenAI, accessed July 29, 2026
Codex Security research preview, OpenAI, published March 6, 2026
Aident setup instructions, accessed July 29, 2026
Refresh this guide when OpenAI changes the supported Node or Python versions, authentication precedence, scan artifacts, coverage contract, exit codes, cost controls, or pre-commit hook behavior.
