OpenQodex

AI agents: read the agent guide. After the install, ~/.openqodex/bin/openqodex guide for-agents prints the guide for the installed version.

OpenQodex reviews your code change before you push it. Your change is the commits you have not pushed plus everything uncommitted. OpenQodex runs on your machine, from your coding agent or your terminal.

First, OpenQodex runs the scanners that fit the files you changed. A scanner is a program that checks code without a model, such as gitleaks or semgrep. A finding is one problem at one place in the code, with a severity. OpenQodex keeps the scanner findings on the lines you changed. It drops findings in test fixtures and in rules you switched off.

Then OpenQodex starts a reviewer: a separate Claude Code or Codex process on your own login. By default, the agent that wrote the code does not review it. The reviewer must raise or drop each scanner finding, with a reason. Scripts check that it answered every scanner finding. They also check that it was given every changed line. Then you choose which findings your agent fixes.

Where it runs

Coding agent	Starts a review	Can be the reviewer	Push gate
Claude Code	yes	yes	yes
Codex CLI	yes	yes	yes, after you trust the hook in Codex
Cursor	yes	no	no, a rule asks Cursor to review
Cline	yes	no	no, a rule asks Cline to review

In Cursor and Cline, the review needs Claude Code or Codex installed as the reviewer. A push gate is a hook that looks for a review before your agent runs git push.

Requirements

• Node 22 or newer, and git.
• macOS or Linux. CI runs the gate on Node 22, on macOS and on Ubuntu Linux. No test runs on Windows or WSL.
• For a full review: Claude Code or Codex, installed and logged in. OpenQodex needs no account or API key of its own.
• Some scanners need a language runtime that OpenQodex does not install. brakeman and rubocop need Ruby. golangci-lint needs Go. cargo-deny needs Cargo.

Install

For people, in your terminal:

npx openqodex init

In a terminal, init finds Claude Code, Cursor, Codex CLI and Cline on your machine. It lists the files it will write. It asks you once. It starts the scanner downloads that your repository needs. Then it reviews your current change when a reviewer can start.

After the install, say to your agent: "review my change with openqodex". In your own terminal, run ~/.openqodex/bin/openqodex review. That path is the launcher, a small script that init writes. An npx install puts no openqodex on your PATH.

For agents, the same install with no question:

npx -y openqodex@0.12.0 init --yes --agent <host>

<host> is claude-code, codex, cursor or cline. In its default sandbox mode, Codex gives commands no network. From Codex, run this line in your own terminal. The quickstart has a prompt to paste into your agent.

To install only the skill, run npx skills add openqodex/openqodex -g. That installs no push gate and downloads no scanner. A later init replaces that skill with the skill that init installs.

OpenQodex itself collects no usage data. The built-in scanners, as OpenQodex runs them, send no code. The reviewer sends your change to the model service of your Claude Code or Codex login. The privacy page lists each network use of this version.

What it does today

• openqodex review reviews your change in one command.
• It writes report.html, report.md, report.json and report.sarif. SARIF is a standard JSON format for scanner results.
• At the end, it prints a receipt. The receipt holds the verdict, one line per finding and the path of report.html. Here is an example report.
• The skill tells your agent to show you the receipt. It tells the agent to ask "Fix all, or tell me which?". It tells the agent to fix only the findings you name.
• review --all reviews every file of the repository, less the paths that review.paths.exclude leaves out.
• review reviews a branch. review '#42' reviews a pull request.
• A review is complete only when every stage ran. Otherwise, review prints "Review incomplete" with what is missing. Then it exits 2.
• The push gate inside your agent looks for a review of your current work. It does not know what a push sends. For a plain git push, it asks whether your current work has a passing review. For any other push command, it says it cannot tell. The git pre-push hook that init adds checks the exact commits a push sends, for each git push that runs git hooks. git push --no-verify skips that hook.
• Both warn by default. They block only when .openqodex/config.yaml sets review.block_on_severity. Severities run from critical through major, minor and nitpick to info. A finding at or above the set severity blocks the push.
• The GitHub Action runs the full review on a pull request when the workflow gives it an Anthropic API key. Without a key, it runs the scanners only. The pre-commit hook also runs the scanners only.
• openqodex graph answers questions about the code, such as who calls a function. An MCP server is a local tool server that your agent starts. init gives your agent the graph questions through an MCP server. For the Cline VS Code extension, init prints the entry for you to add.
• --offline skips semgrep, osv-scanner, kubeconform and cargo-deny, the built-in scanners that use the network. It also stops scanner downloads. The reviewer still sends your change to its model service. An approved custom scanner still runs its own command.
• npx openqodex demo builds a small repository with planted bugs. Then it scans that repository.

What i