Bug Hunter: an adversarial review skill for AI coding agents

The gap Bug Hunter targets: agents that agree with themselves

A single model asked to review code tends to produce plausible findings and then accept them. Bug Hunter splits that job across roles. The README describes a Hunter that finds possible bugs, a Skeptic that challenges each claim, and a Referee that decides what the evidence supports. The pipeline is drawn as triage, recon, Hunter, Skeptic, Referee, Fixer and verification.

The audience is narrow and specific. This is not a standalone scanner you run in CI from a shell script. It is a skill installed into an agent host: Claude Code, Codex, Cursor, GitHub Copilot, Kiro, Windsurf, OpenCode, Factory Droid CLI, or any other file-based agent. If your workflow does not already go through one of those, the installation step has nowhere to land.

The default posture matters more than the marketing. The README states the default run only scans and reports, is single-pass unless --loop is explicitly requested, and that editing, autonomous fixing and commits each require explicit permission. That is a deliberate choice against the grain of agents that start rewriting files on the first turn.

How the adversarial pipeline and verification actually work

The mechanism visible in the repository is a chain of artifacts rather than a chat transcript. The package ships JSON schemas for findings, coverage, fix-plan, fix-report, fix-strategy and fixer-scope, plus scripts named triage.cjs, artifact-planner.cjs, chunk-scheduler.cjs, schema-validate.cjs and render-report.cjs. Findings are validated against a schema, not just printed as prose. That is what makes the Referee role meaningful: a claim either satisfies the findings contract or it does not.

v3.2.0 adds adaptive execution profiles. Triage risk, security scope, benchmark evidence, stability, calibration and token efficiency select one of three behaviors: fast, balanced or assurance. This is the part I would scrutinize hardest. Adaptive profile selection means two runs over the same repository can take different paths, and the README does not publish the thresholds that move a run between profiles.

Verification is hybrid and fail-closed. The README says it runs argv-only tests, type checks, static checks, fuzz checks and security-static checks, and fails closed when required verification fails or is unavailable. Fail-closed is the right default for a tool that can authorize a Fixer, but it also means an environment missing a required check produces a failure rather than a partial result.

Caching is exact-match. Evidence is reused only when source content, protocol identity, role and relevant configuration match exactly, so changed source cannot inherit stale conclusions. Hypothesis-driven retrieval prioritizes direct files, symbols, dependencies, dependents, cross-references and trust boundaries under hard context budgets. The README does not document how those budgets are set or how to raise them.

Installing Bug Hunter and running a first scan

The README gives two install routes. The first pulls the current GitHub main branch, which the README notes may be ahead of the published npm release. Replace codex with a target from the agent table, for example claude-code, cursor, copilot, kiro, windsurf, opencode, droid or agents.

npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz install --agent codex
npx --yes https://github.com/codexstar69/bug-hunter/archive/refs/heads/main.tar.gz doctor --agent codex

The second command is a health check. Run it and read the output before auditing anything; if the skill landed in the wrong directory, doctor is where you find out. The npm route is the alternative when you want the published release rather than main.

npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter install --agent codex
npm exec --yes --package=@codexstar/bug-hunter@latest -- bug-hunter doctor --agent codex

The README instructs you to restart the agent if it was open during installation. Then open the repository you want audited and send the recommended first prompt, which is scan-only and single-pass.

Use the bug-hunter skill to scan this repository. Do not edit files.
Return the final report and call out every item that needs manual review.

Expect a final report with findings, not a patch. The README says to request --loop when complete queued coverage is required, and to use --plan or --preview when source edits must be impossible. The closest flag-based fix mode is /bug-hunter --fix --approve, where --approve requests the host agent's reviewed permission mode; the host, not Bug Hunter, decides when approval prompts appear.

Where Bug Hunter is the wrong tool

The bundled benchmark is the first limitation, and the README states it plainly. The deterministic regression fixture records precision 1.00, recall 1.00, F1 1.00, repeat stability 1.00, zero false positives, median 12,090 tokens per true positive, p95 duration 61.3s and expected calibration error about 0.048. The README then says these figures validate the bundled harness and fixture and are not an independent benchmark of every repository or model. Treat any 1.00 as a property of the fixture, not of your codebase.

Cost is the second. The same fixture reports a median of 12,090 tokens per true positive. A repository with a low density of real bugs will spend that budget repeatedly to surface little. There is no published guidance in the README on capping spend per run.

Third, this is not a substitute for a deterministic scanner in CI. The bundled workflows cover PR-focused security review, full repository security review, STRIDE threat modeling, vulnerability validation and dependency CVE scanning, but the core product is an agent skill. Its output depends on the host model, the retrieval context and the selected profile. If your compliance process needs a reproducible tool exit code with no model in the loop, a static analyzer is the correct instrument.

Finally, the Fixer is gated by design. If what you actually want is an agent that opens pull requests unattended, Bug Hunter's default posture is the opposite of that, and the README warns against --autonomous and --auto-commit unless you intend to grant those permissions.

How it differs from a conventional static analyzer

The obvious comparison is a rule-based analyzer such as Semgrep, and the difference is not quality but mechanism. A rule engine matches patterns you wrote or imported. It produces the same result on the same input every time, and it cannot tell you that two files interact badly unless someone wrote a rule for that interaction.

Bug Hunter instead spends model tokens to form hypotheses, retrieve the files, symbols, dependencies and dependents around them, and then argue about the result across three roles. That buys you reasoning about logic errors and runtime bugs that no pattern expresses, and it costs tokens, latency and non-determinism. The README's own repeat stability figure of 1.00 applies to the bundled fixture, not to arbitrary repositories.

The two are complementary in practice. A rule engine is cheap enough to run on every commit and produces a stable baseline. Bug Hunter is the expensive second pass you point at an authentication module or a payments path, where the class of bug you fear is a logic error rather than a known pattern. Running Bug Hunter on every commit, with --loop and the assurance profile, is the way to turn a targeted review into an unbounded bill.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-17. The most recent tagged release is v3.1.0, dated 2026-08-03 and titled Complete Safety and Reliability Hardening. Before that, v3.0.8 and v3.0.7 landed on 2026-03-13 and 2026-03-12, with v3.0.7 introducing the Skills-First Architecture. package.json declares version 3.2.0, and the README describes v3.2.0 source while noting the latest published npm release may lag GitHub main. That gap is the practical upgrade hazard: installing from npm and installing from the main tarball can give you different code, and the README's own commands reflect both paths.

Upgrade cost is mostly re-verification, not migration. Because findings and fix plans are validated against versioned JSON schemas in the schemas/ directory, an upgrade that changes a schema can invalidate stored artifacts or a resume state. The README mentions source hashes, resume identity and coverage state as explicit parts of source integrity, and says source drift is rejected. If you keep artifacts between runs, check the schema files after each upgrade rather than assuming continuity.

The licence is MIT, declared in package.json and shown by the badge in the README. MIT permits commercial use and modification with the copyright notice retained. This is a description of the licence text, not legal advice; if you redistribute the skill inside a product, have your own counsel read the terms.

Editorial conclusion

Adopt Bug Hunter if you already drive a file-based coding agent and want an evidence-backed second pass over security-sensitive code with scan-only defaults and explicit approval before edits. Do not adopt it if you need an independent benchmark before trusting a scanner, if your agent cannot load a skill directory, or if you want unattended commits; --autonomous and --auto-commit exist, but the README tells you not to use them unless you intend to grant those permissions. Verify first that Node.js is 22 or newer, that npx can reach the GitHub tarball or npm, and that bug-hunter doctor --agent <target> reports a clean install before you point it at a real repository.

Frequently asked questions

Official sources

1. codexstar69/bug-hunter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases