codexstar69/bug-hunter

What it solves

Bug Hunter is designed to reduce the high volume of false positives common in AI-driven code reviews. Instead of presenting a long list of plausible but unverified claims, it uses an adversarial process to ensure that only evidence-backed, reachable runtime bugs and security vulnerabilities are reported.

How it works

The project implements a multi-stage, role-based pipeline that separates the discovery of bugs from their verification:

1. Risk Triage: A deterministic pre-pass that scores files by risk to prioritize the scan order without using model tokens.
2. The Adversarial Trio:
   • Hunter: Identifies potential bugs, providing evidence and runtime triggers.
   • Skeptic: Attempts to disprove the Hunter's claims by tracing code and identifying missing context.
   • Referee: Evaluates the evidence from both sides to issue a final verdict (REAL_BUG, NOT_A_BUG, or MANUAL_REVIEW).
3. Verification & Reporting: The system can run hybrid verification (tests, type checks, fuzzing) and generates structured JSON artifacts and Markdown reports.
4. Remediation: If authorized, it creates a fix plan and applies approved edits.

Who it’s for

It is built for developers and security auditors using AI coding agents (such as Claude Code, Cursor, GitHub Copilot, or Windsurf) who need a high-precision security audit or code review process that minimizes noise.

Highlights

• Adversarial Review: Uses a Hunter-Skeptic-Referee model to challenge findings before they reach the user.
• Measurable Quality: Includes a benchmark quality gate to track precision, recall, and F1 scores.
• Adaptive Execution: Offers fast, balanced, and assurance profiles based on the risk and scope of the audit.
• Fail-Closed Safety: Source edits and autonomous fixing require explicit permission; the system rejects source drift to maintain integrity.
• Broad Agent Support: Compatible with a wide range of file-based AI coding agents via a portable natural language interface.