A Claude Code skill that scans repository branch changes using 4 parallel analysis agents (Bug, Security, Performance, Compatibility), then cross-verifies findings with Claude + Codex and produces two companion reports:
- Interactive HTML report — sortable/filterable issue table, severity chart, detailed issue cards
- Static Markdown report — grep-friendly, paste-ready for PR descriptions and tickets
Use /release-scan when you want a fast pre-merge risk assessment, a second opinion on a release branch, or a lightweight security review.
STEP 0 → Parse args + resolve repo directory
STEP 1 → Fetch branch + compute MERGE-BASE (not the master tip!) for accurate PR diff
STEP 2 → Launch 4 parallel agents (Bug / Security / Performance / Compatibility)
STEP 3 → Consolidate into a canonical issue list
STEP 4 → Write interactive HTML report
STEP 5 → Launch 3 verifier agents in parallel:
• Claude — verify Critical + High (cross-model)
• Codex — verify Critical + High (cross-model)
• Claude — verify Medium (single-model)
STEP 6 → Write Markdown companion report (same timestamp as HTML)
Why merge-base? origin/master..origin/branch shows changes from both sides of the divergence — including master-only commits that were never part of the branch. The merge-base restricts the diff to only what the branch actually introduced, killing a huge class of false positives.
Why cross-model verification? A single model's confidence in its own finding is a bad signal. Two independently-reasoning models agreeing on a CONFIRMED verdict is a much stronger indicator that an issue is real. Medium issues get single-model triage (cost/value trade-off — Medium isn't ship-blocking).
# Project-scoped (recommended — lives with the repo):
git clone https://github.com/<your-username>/release-scan .claude/skills/release-scan
# Or user-scoped (available everywhere):
git clone https://github.com/<your-username>/release-scan ~/.claude/skills/release-scanscans.py is an optional tracker that records scan runs, agent prompts, and issue verdicts to a local SQLite DB — handy for answering "what kinds of findings actually get fixed?" across repos over time.
cd .claude/skills/release-scan
python3 scans.py init-dbThis creates scans.db next to the script. It's gitignored by default — your tracking data never leaves your machine.
🔑 Codex is the biggest quality lever in this skill. Cross-model verification is what separates a useful pre-merge scan from a noisy pile of single-model false positives. For the best review, you should have Codex wired up. Without it, Critical + High findings are verified by Claude alone — the skill still runs, but you lose the cross-model consensus signal and the Codex column in the consensus table will read
N/A.
The skill routes verification calls through the Codex plugin for Claude Code, using the gpt-5.3-codex model via the plugin's shared runtime. The plugin is the current integration path (earlier versions of this skill used the Codex MCP, which is now deprecated).
From inside a Claude Code session:
/plugin marketplace add openai/codex-plugin-cc # register the OpenAI marketplace (one-time)
/plugin install codex@openai-codex # install the codex plugin
/codex:setup # one-shot health check: Node, npm, codex CLI, auth, runtime
!codex login # run only if /codex:setup reports auth is missing
A healthy /codex:setup output looks like:
ready: true
node: ✅ v22+
npm: ✅ 10+
codex: ✅ codex-cli 0.12x.x (advanced runtime available)
auth: ✅ ChatGPT login active (verified)
Once ready: true, the skill's Agent 6 will automatically route through gpt-5.3-codex.
- Node 20+ and npm 10+ — the plugin ships a Node-based companion runtime
- A ChatGPT subscription or an OpenAI API key — Codex authenticates against either
- Network access to OpenAI's app server
If the plugin is not installed or Codex is unreachable, the skill detects it and falls back to Claude-only verification. Expect the Markdown report's consensus table to show Codex: N/A (plugin not installed) for Critical + High rows.
/release-scan <repo>:<branch> [base_ref]
| Arg | Required | Default | Example |
|---|---|---|---|
<repo> |
yes | — | my-service, backend, api-core |
<branch> |
yes | — | feature/new-login, release/1.0.0 |
[base_ref] |
no | origin/master |
origin/main, release/1.0, v2.3.1 |
<repo> is matched against git-repo subdirectories of the current working directory. First match wins:
- Exact —
my-servicematches./my-service/ - Suffix —
apimatches./my-api-service/(dir ends with-api/_api) - Contains —
corematches./backend-core-module/
If multiple repos match, the skill lists them and asks you to be more specific.
/release-scan my-service:feature/new-login
/release-scan backend:feature/PROJ-1234 release/1.0
/release-scan api:feature/rewrite origin/develop
Two files written to the target repo root:
claude-release-scan-<repo>-<branch>-<YYYYMMDD-HHMMSS>.html ← interactive
claude-release-scan-<repo>-<branch>-<YYYYMMDD-HHMMSS>.md ← grep-friendly
Open the .html in any browser — it has search, per-column sort, severity/category/verdict filters, and a severity distribution bar chart.
| Agent | Focus |
|---|---|
| Bug Finder | Logic errors, resource leaks, concurrency bugs, exception handling, data validation, API misuse |
| Security Scanner | Injection (SQL/command/LDAP), auth/authz gaps, sensitive data exposure, input validation (XSS/path traversal/deserialization), crypto issues, access control |
| Performance Analyzer | N+1 queries, memory issues, inefficient algorithms, blocking operations, resource utilization, API inefficiency |
| Compatibility Analyzer | Backward-compat breaks, data migration needs, API contract changes, state/transition compat, behavioral drift |
Each agent returns findings with severity (Critical / High / Medium / Low), file path + line number, description, impact, and a suggested fix.
| Severity | Meaning | Gets verified? |
|---|---|---|
| Critical | Ship-blocker — data loss, security breach, production outage likely | Claude + Codex (cross-model) |
| High | Ship-blocker — significant correctness or security risk | Claude + Codex (cross-model) |
| Medium | Pre-merge cleanup — noticeable quality gap, not ship-blocking | Claude (single-model) |
| Low | Follow-up — stylistic or defensive polish | Unverified (listed in table only) |
| Dismissed | Refuted after verification — kept for audit trail | — |
An optional SQLite-backed tracker for running the skill across many repos and retroactively learning which kinds of findings authors actually fix. Schema:
scans— one row per/release-scaninvocation (repo, branch, base, timestamp)agent_runs— one row per subagent call (agent name, role, model, full prompt, output summary)issues— one row per issue surfaced (code, title, category, severity, verdict, fix status)detections— many-to-many link between issues and agent runs
python3 scans.py init-db # bootstrap schema
python3 scans.py insert-scan --repo … --branch … # record a scan
python3 scans.py insert-issue --scan-id … # record an issue
python3 scans.py update-fix --issue-id … --fix-status fixed --fix-commit-sha …
python3 scans.py list-scans # list all scans
python3 scans.py show-scan --scan-id 1 # dump one scan + issues
python3 scans.py fixed-issues # signal query: what got fixed?Run python3 scans.py --help for the full surface.
release-scan/
├── skill.md # The skill instructions (Claude reads this)
├── report-template.html # HTML report template with placeholders
├── scans.py # Optional SQLite tracker CLI
├── .gitignore # Excludes scans.db and generated reports
├── LICENSE # MIT
└── README.md # This file
- Claude Code — primary host for the skill
- Python 3.8+ — for the optional
scans.pytracker (uses stdlib only; nopip installneeded) - git — the skill uses
git fetch,git diff,git show,git merge-base - (Strongly recommended) Codex plugin for Claude Code — routes cross-model verification to
gpt-5.3-codex; without it the skill verifies with Claude alone and loses its most valuable signal. See install instructions above. - Node 20+ and npm 10+ — required only if you install the Codex plugin (for its companion runtime)
MIT — see LICENSE. Feel free to fork, adapt the agent prompts to your team's conventions (add your framework's common mitigations to the verifier checklist, tune severity language, swap out the HTML theme, etc.).
Built by vhreal. Issues and pull requests welcome.