Skip to main content

​
Paste this prompt into your agent

The agent installs the skill, runs the review and tells you the result. The steps below do the same by hand.

​
Before you start

  • Node 22 or newer, and git.
  • macOS or Linux. On Windows, use WSL.
  • A git repository with a change in it.

​
1. Install into your agent

Run this in your own terminal, not inside the agent:
init finds Claude Code, Cursor, Codex CLI and Cline on your machine. It prints each file it will write, then asks once. --yes skips the questions. agents lists every file for each agent. Inside a repository, init also:
  • asks whether to add the git pre-push hook, so every push from that repository gets a scan, from an agent or by hand. The default is yes.
  • adds a short section to each agent’s instruction file, such as ~/.claude/CLAUDE.md for Claude Code: when a feature or fix is done, review it with openqodex in a separate subagent, so the agent that wrote the code does not judge its own work. It prints the section before writing it.
  • creates .openqodex/config.yaml and .openqodex/custom-instructions.md. Commit both. Write in custom-instructions.md what a reviewer of your repository must know: conventions, what never to flag, what always to check. The review brief carries it word for word.
init also starts the scanner downloads that your repo needs, in the background. Running it outside the agent matters: some agents run commands in a sandbox that cannot download. Codex only: open Codex, run /hooks and trust the OpenQodex hook. Codex runs a new hook only after you trust it.

​
2. Ask for a review

Say to your agent:
The agent hands the review to a separate subagent where it can, and tells you when it cannot. The reviewer runs openqodex review --agent. That command works out the change, runs the scanners and prints a brief. The agent verifies each scanner finding, reviews the change itself, and writes its findings to a file. Then it runs openqodex review --finalize, which checks those findings without a model and writes the report. To review the whole repository instead of one change, say:
The agent runs openqodex review --all --agent. The scanners check every file, and the brief tells the agent where to start: the most-called functions and the files with the most scanner hits. See docs/cli.md for the details.

​
3. Read the report

The agent tells you the verdict and the most serious findings. The full report is in .openqodex/reviews/<time>-<id>/report.md in your repo. .openqodex/.gitignore keeps the reports out of git; git status shows only the two files above and that .gitignore, the first time. The verdict is passed unless .openqodex/config.yaml sets review.block_on_severity and a finding meets it. With no config, OpenQodex warns and never blocks.

​
Try it on the demo repo

demo builds a small repo with planted bugs: a secret, a SQL injection, a bad Dockerfile, a vulnerable lockfile, a shell bug and a workflow injection. It scans the change and prints the report. Then open the folder in your agent and ask for a review.

​
Without an agent

openqodex scan runs the scanners on the change and prints the report:
It is the same check the git hook, the pre-commit hook and the GitHub Action run.

​
First run

Scanners download on first use into ~/.openqodex/tools/. Only the scanners your change needs download. A scanner still installing after 45 seconds keeps going in the background. The report lists it as installing. It joins the next run. One measured first run: an Apple Silicon Mac, an empty tool folder, a line of 2 MB per second. The first demo printed its report in under a minute. That report held the scanners that had finished installing and listed the rest as installing. The next scan included all eight scanners the demo needs. They take about 700 MB of disk. To download every scanner now:

​
Next

  • config: block pushes at a severity, exclude paths, switch scanners off.
  • custom-scanners: add any scanner by its GitHub link.
  • security: what runs and what is sent where.