bugs.doctor

Precision-engineered AI code reviewer, bug detector, preventer, and fixer for GitHub PRs.

Architecture

flowchart LR
    subgraph Stage1["Stage 1 — Triage"]
        A1[Diff Processor] --> A2[Semantic Chunker]
        A2 --> A3[Risk Scorer]
        A3 --> A4[Static Analyzer]
        A4 --> A5{SKIP / SHALLOW / DEEP}
    end

    subgraph Stage2["Stage 2 — Context Assembly"]
        B1[Dependency Graph] --> B2[Invariant Extractor]
        B2 --> B3[Test Surface Mapper]
        B3 --> B4[History Miner]
    end

    subgraph Stage3["Stage 3 — Multi-Agent Review"]
        C1[Analyzer] --> C2[Critic]
        C2 --> C3[Verifier]
        C3 --> C4[Ensemble Consensus]
    end

    subgraph Stage4["Stage 4 — Confidence & Filtering"]
        D1[Score & Rank] --> D2[Dedup & Merge]
        D2 --> D3[Top-K Gate]
    end

    subgraph Stage5["Stage 5 — Fix & Validate"]
        E1[Patch Generator] --> E2[Syntax Check]
        E2 --> E3[Test Synthesis]
        E3 --> E4[Sandbox Run]
    end

    subgraph Stage6["Stage 6 — Delivery & Learning"]
        F1[PR Comments] --> F2[Telemetry]
        F2 --> F3[Feedback Loop]
        F3 --> F4[Per-Repo Tuning]
    end

    Webhook["GitHub Webhook"] --> Stage1
    Stage1 -->|DEEP| Stage2
    Stage2 --> Stage3
    Stage3 --> Stage4
    Stage4 --> Stage5
    Stage5 --> Stage6

Quick Start

1. Install the CLI

# Via install script
curl -fsSL bugs.doctor/install.sh | sh

# Or via npm
npm install -g @bugs.doctor/cli

2. Log in to your bugs.doctor account

bugs.doctor login

Opens your browser to authenticate with the account you registered at bugs.doctor.

3. Review a PR

# From a cloned repo
bugs.doctor review --pr 42

# Or with auto-merge for high-confidence fixes
bugs.doctor fix --auto-merge-threshold=0.95

4. Add to your coding agent (optional)

bugs.doctor skill install --claude

Then say "review this PR" in Claude Code or Cursor.

Features

• Diff Analysis — Parse unified diffs and map changes at the symbol level using tree-sitter
• Semantic Chunking (SCU) — Group hunks into semantic change units (function/method/class level)
• Risk Scoring — Deterministic 0-100 score per SCU based on file path, control flow, and historical hotspots
• Static Analysis Grounding — Semgrep, CodeQL, and language-native linters feed evidence into the LLM pipeline
• Multi-Agent Review — Analyzer hypothesizes, Critic attacks, Verifier grounds with symbol resolution
• Ensemble Consensus — N=3 sampling with >=2 agreement required to surface a finding
• Confidence Scoring — 7-factor weighted scoring with sigmoid transform; only >=0.75 surfaces
• Patch Generation — Minimal, style-preserving unified diffs for null-deref, off-by-one, missing-await, and unused-import bugs
• Secret Scanning — Detect leaked AWS keys, GitHub tokens, Stripe live keys, private keys, and JWTs in PR diffs
• Kill Switch — Emergency circuit breaker at global, org, or repo scope with audit logging
• Rate Limiting — Token bucket and sliding window limiters for webhook and API protection
• Learning Loop — Per-repo suppression/boost tuning with A/B testing and security guardrails
• OpenTelemetry Tracing — Full pipeline observability with Jaeger and ClickHouse

Documentation

| Document | Description | |----------|-------------| | DESIGN.md | Full system design, quality targets, and architecture decisions | | docs/api.md | HTTP API reference (webhooks, health, metrics) | | docs/runbook.md | Operational runbook for deployment and incident response | | docs/onboarding.md | Developer onboarding guide | | SECURITY.md | Security policy and vulnerability reporting | | CONTRIBUTING.md | Contribution guidelines and code standards |

Tech Stack

| Layer | Technology | |-------|------------| | Language (Core) | TypeScript 5.4+ (strict mode) | | Language (Agents) | Python 3.11+ (Poetry) | | Web Framework | Express.js | | Queue | BullMQ (Redis) | | Database | PostgreSQL 16 + pgvector | | Metrics | Prometheus + ClickHouse | | Tracing | OpenTelemetry + Jaeger | | AST / Diff | tree-sitter | | Static Analysis | Semgrep, CodeQL | | Sandbox | Firecracker / nsjail | | Monorepo | pnpm workspaces + Turbo |

License

MIT — see LICENSE for details.