{"id":50406743,"url":"https://github.com/shanemhamilton/bugsweep","last_synced_at":"2026-05-31T02:00:44.650Z","repository":{"id":360698163,"uuid":"1247173103","full_name":"shanemhamilton/bugsweep","owner":"shanemhamilton","description":"AI bug-hunting \u0026 auto-fix for your codebase — a Claude Code \u0026 Codex skill. An adversarial Hunter→Skeptic→Referee review finds security vulnerabilities, logic errors \u0026 race conditions across your whole repo, then fixes them on a throwaway branch you control. Safe for unattended runs.","archived":false,"fork":false,"pushed_at":"2026-05-27T13:56:29.000Z","size":141,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T15:06:15.914Z","etag":null,"topics":["agentic-ai","ai-agents","ai-code-review","ai-developer-tools","anthropic","automated-code-review","bug-detection","claude","claude-code","code-quality","code-review","codex","developer-tools","devtools","llm","sast","security","security-tools","static-analysis","vulnerability-scanner"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shanemhamilton.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T01:39:31.000Z","updated_at":"2026-05-27T13:56:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shanemhamilton/bugsweep","commit_stats":null,"previous_names":["shanemhamilton/bugsweep"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/shanemhamilton/bugsweep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanemhamilton%2Fbugsweep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanemhamilton%2Fbugsweep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanemhamilton%2Fbugsweep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanemhamilton%2Fbugsweep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shanemhamilton","download_url":"https://codeload.github.com/shanemhamilton/bugsweep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shanemhamilton%2Fbugsweep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","ai-code-review","ai-developer-tools","anthropic","automated-code-review","bug-detection","claude","claude-code","code-quality","code-review","codex","developer-tools","devtools","llm","sast","security","security-tools","static-analysis","vulnerability-scanner"],"created_at":"2026-05-31T02:00:35.495Z","updated_at":"2026-05-31T02:00:44.635Z","avatar_url":"https://github.com/shanemhamilton.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bugsweep — AI bug hunting \u0026 auto-fix for your codebase\n\n[![Release](https://img.shields.io/github/v/release/shanemhamilton/bugsweep?sort=semver\u0026label=release\u0026color=2563eb)](https://github.com/shanemhamilton/bugsweep/releases)\n[![License: MIT](https://img.shields.io/github/license/shanemhamilton/bugsweep?color=2563eb)](LICENSE)\n[![Works with Claude Code](https://img.shields.io/badge/Claude%20Code-skill-d97757)](https://claude.ai/code)\n[![Works with Codex](https://img.shields.io/badge/Codex-skill-412991)](https://github.com/openai/codex)\n[![Dependencies: none](https://img.shields.io/badge/dependencies-none-2563eb)](#configure)\n\n\u003e **An autonomous, adversarial AI code-review and bug-fixing skill for [Claude Code](https://claude.ai/code) and [Codex](https://github.com/openai/codex).** It finds real security vulnerabilities, logic errors, race conditions, and data-integrity bugs across your whole repository — then, when you let it, fixes them on a throwaway git branch you fully control. Safe enough to run unattended overnight.\n\nA Claude Code and Codex skill that finds and fixes bugs in your codebase — safely enough\nto run unattended, even fully autonomously overnight. It hunts for real runtime bugs\n(security holes, logic errors, race conditions, bad error handling, data-integrity\nissues), and when you let it, fixes them on a throwaway branch with automatic revert if a\nfix breaks anything.\n\nIt does four things that make it effective on real, large codebases:\n- **Whole-repo context.** Before hunting, it builds a distilled model of your\n  architecture — trust boundaries, sensitive sinks, and the call chains into them — so it\n  catches *large* cross-file bugs (like a missing authorization check on one path into a\n  database write), not just local ones.\n- **Stack-aware research.** It detects your languages/frameworks and primes itself with a\n  curated library of the bugs common to that kind of code (with optional, off-by-default\n  web research for version-specific advisories).\n- **Adversarial review.** Every finding runs a gauntlet — a Hunter finds it, a Skeptic\n  tries to disprove it, and a neutral Referee makes the final call — so false positives\n  rarely reach the fix stage.\n- **Context continuity.** All progress is written to disk, so on a long run it can reset\n  its working memory and keep going without losing findings, fixes, or coverage.\n\n## The one thing to understand\n\n**The worst case for any run is a branch you delete.** bugsweep never works on your real\nbranch, never pushes anywhere, never merges, and never deletes files. It cuts a fresh\n`bugsweep/\u003ctimestamp\u003e` branch, makes its fixes there as one commit each, and re-runs your\ntests after every fix — automatically undoing any fix that breaks something. You review\nthe branch and decide what to keep. You are always the merge gate.\n\nThe dangerous, irreversible operations (branching, stashing your work, reverting) are\ndone by short shell scripts in `scripts/` that you can read in a few minutes — not by the\nAI's judgment. That's what makes it trustworthy for long unattended runs.\n\n## How it works\n\n### Full run pipeline\n\n```mermaid\nflowchart TD\n    A([\"/bugsweep invoked\"]) --\u003e B\n\n    subgraph scripts [\"⚙️ Shell scripts — deterministic, auditable\"]\n        B[\"preflight.sh\\ncut bugsweep/\u0026lt;timestamp\u0026gt; branch\\nstash uncommitted work\\nwrite RUN_DIR + ledger\"]\n        C[\"run_checks.sh baseline\\nrecord test / build / lint state\"]\n        L[\"run_checks.sh verify\\ndiff against baseline\"]\n        Q[\"guard.sh\\ncheck iteration / time / fix caps\"]\n        FIN[\"finalize.sh\\nrestore original branch\\npop stash\\npersist audit coverage\"]\n    end\n\n    subgraph ai [\"🤖 AI phases — reasoning only, no git ops\"]\n        D[\"context-build\\nbuild whole-repo model\\narchitecture · trust boundaries\\nsensitive sinks · call chains\"]\n        E[\"research\\nprime with stack-specific\\nanti-pattern catalogs\"]\n        F[\"hunt\\nbatch through files\\nHunter generates candidates\"]\n        G[\"challenge\\nSkeptic tries to disprove\\neach candidate\"]\n        H[\"referee\\nneutral final verdict\"]\n        K[\"fix.md\\nsurgical minimal patch\\none commit per confirmed bug\"]\n    end\n\n    B --\u003e C --\u003e D --\u003e E --\u003e F --\u003e G --\u003e H\n    H --\u003e |detect-only| RPT[\"📄 write report\\nno code changes\"]\n    H --\u003e |fix / approve / autonomous| K\n    K --\u003e L\n    L --\u003e |pass| N[\"commit fix\\nappend to ledger\"]\n    L --\u003e |fail| O[\"auto-revert\\nquarantine bug\"]\n    N --\u003e Q\n    O --\u003e Q\n    RPT --\u003e FIN\n    Q --\u003e |CONTINUE| F\n    Q --\u003e |STOP| FIN\n    FIN --\u003e R([\"User reviews\\ngit diff main..bugsweep/\u0026lt;timestamp\u0026gt;\"])\n```\n\n### Adversarial review — why bugsweep has a low false-positive rate\n\nEvery candidate finding runs a three-role gauntlet before it can be fixed or reported. The model never evaluates its own findings.\n\n```mermaid\nflowchart LR\n    H[\"🔍 **Hunter**\\n`hunt.md`\\nfinds candidate bug\\nwith supporting evidence\"]\n    S[\"🛡️ **Skeptic**\\n`challenge.md`\\ntries to disprove:\\nalternate explanations\\ncode paths that prevent the bug\\ntest coverage that catches it\"]\n    R[\"⚖️ **Referee**\\n`referee.md`\\nneutral final verdict\\nbased on both sides\"]\n\n    H --\u003e S --\u003e R\n\n    R --\u003e |\"Confirmed\\n(high confidence)\"| FIX[\"Promoted to fix queue\"]\n    R --\u003e |\"Dismissed or uncertain\"| DISC[\"Dropped — not fixed\\nnot reported\"]\n```\n\n### Coverage-first state — how bugsweep finds bugs in old, unchanged code\n\nbugsweep is not a diff scanner. Every file in the repo is always in scope. Cross-run state lets it track which files have been reviewed at the current catalog version and prioritize the ones that haven't.\n\n```mermaid\nflowchart TD\n    subgraph state [\"📁 .bugsweep/state/  (persists across runs)\"]\n        AL[\"audit-log.jsonl\\nper-file: last-audited run, catalog version\"]\n        RJ[\"risk.jsonl\\nrisk scores per file\"]\n        MJ[\"meta.json\\ncurrent catalog version\"]\n    end\n\n    P[\"preflight.sh\\n→ state.sh prime\"] --\u003e|reads state| PC[\"prior-coverage.json\\nbatch priority plan\"]\n\n    PC --\u003e T1[\"**Tier 1 — Critical**\\nnever-audited\\nstale (catalog bumped)\\ncontent-changed\\nhigh-risk\\nsink-bearing\"]\n    PC --\u003e T2[\"**Tier 2 — Re-confirm**\\nrecently audited, fresh\"]\n\n    T1 --\u003e HUNT[\"hunt loop\"]\n    T2 --\u003e HUNT\n\n    HUNT --\u003e FIN[\"finalize.sh\\n→ state.sh persist\\nupdate audit-log + risk\"]\n    FIN --\u003e|next run| P\n```\n\n## Install\n\n**One command — works for Claude Code, Codex, or both:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash\n```\n\nThe script auto-detects which AI tools you have installed (`~/.claude` → Claude Code,\n`~/.codex` → Codex) and sets up each one. Re-running it updates in place.\n\n**Force a specific tool:**\n\n```bash\n# Claude Code only\ncurl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --claude\n\n# Codex only\ncurl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --codex\n\n# Both\ncurl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --all\n```\n\n**Pin to a specific release** (instead of tracking the latest `main`):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/shanemhamilton/bugsweep/main/install.sh | bash -s -- --version v0.1.0\n```\n\nRe-running the installer with `--version` checks out that release tag; re-running without\nit returns you to the latest `main`. See [releases](https://github.com/shanemhamilton/bugsweep/releases)\nand the [CHANGELOG](CHANGELOG.md).\n\n**Manual install (if you prefer to inspect first):**\n\n```bash\ngit clone https://github.com/shanemhamilton/bugsweep.git\nbash bugsweep/install.sh          # then delete the clone — it installs to ~/.claude or ~/.codex\n```\n\n**What the installer does:**\n- *Claude Code* — clones to `~/.claude/skills/bugsweep/`. Claude Code auto-discovers skills\n  there; no config needed.\n- *Codex* — clones to `~/.codex/skills/bugsweep/` and appends a stub to\n  `~/.codex/instructions.md` so Codex knows where the scripts live.\n\n## Use\n\nOpen Claude Code (or start Codex) in your project and type one of:\n\n| Command | What it does |\n| --- | --- |\n| `/bugsweep` | Find bugs and write a report. **Makes no changes.** Start here. |\n| `/bugsweep --approve` | Find + fix, but asks you before each fix. Use this to build trust. |\n| `/bugsweep --autonomous` | Find + fix in a loop until clean or a limit is hit. The overnight mode. |\n| `/bugsweep src/api` | Limit the sweep to a folder or file. |\n| `/bugsweep --severity high` | Only fix high/critical bugs; report the rest. |\n\nRecommended path: run `/bugsweep` once to see what it finds, then `/bugsweep --approve`\nto watch how it fixes, then `/bugsweep --autonomous` once you trust it.\n\n## After a run\n\nIt tells you the branch name and how to review:\n\n```\ngit diff \u003cyour-branch\u003e..bugsweep/\u003ctimestamp\u003e\n```\n\nKeep what you like (cherry-pick or merge), and delete the branch if you don't:\n`git branch -D bugsweep/\u003ctimestamp\u003e`. Your original branch and uncommitted work are\nexactly as you left them.\n\n### Repeatable, unattended runs\n\nRunning bugsweep on a schedule makes it dig deeper over time on its own — coverage-first\ncross-run state means each run prioritizes the files it hasn't audited yet. The only thing\nthat accumulates is one `bugsweep/\u003ctimestamp\u003e` branch per run, because bugsweep never merges\nor deletes (you're the merge gate). To keep scheduled runs ending clean, the optional\ncompanion script `scripts/bugsweep-cleanup.sh` automates that gate *after* finalize: it\nmerges the verified fix branch into a branch you choose, deletes it, and prunes old\nabandoned sweep branches — using only plain git, outside the skill's trust contract. See\n[`references/autonomous-maintenance.md`](references/autonomous-maintenance.md) for the\ncopy-paste prompt, settings, and scheduling notes.\n\n## Configure\n\nEdit `config/bugsweep.config.json` to set limits (how long it runs, how many fixes),\nexclude folders, or specify your test/build commands if auto-detect misses them. See\n`references/tuning.md`.\n\n## FAQ\n\n**How is bugsweep different from Snyk, CodeQL, SonarQube, or Dependabot?**\nThose are mostly pattern/diff scanners and dependency auditors. bugsweep is an *agentic*\nreviewer: it builds a whole-repo architecture model and reasons about behavior, so it\ncatches cross-file logic bugs (like a missing authorization check on one path into a\ndatabase write) that pattern matchers miss. It complements those tools rather than\nreplacing them — and it can fix what it finds, not just flag it.\n\n**What languages and frameworks does it support?**\nAny language Claude Code or Codex can read. It ships curated anti-pattern catalogs for\ncommon stacks (JavaScript/TypeScript, Python, Go, Rust, Swift/iOS, and more) and detects\nyour stack automatically to prime the hunt.\n\n**Is it safe to run on a production codebase?**\nYes — that's the design center. bugsweep never works on your branch, never pushes, never\nmerges, and never deletes files. It cuts a throwaway `bugsweep/\u003ctimestamp\u003e` branch, and\nthe irreversible git operations are short shell scripts you can audit in minutes. The\nworst case for any run is a branch you delete.\n\n**Does bugsweep send my code anywhere?**\nNo third-party services, no telemetry, and no network calls — unless you explicitly opt\ninto bounded web research for version-specific advisories (off by default). Your code\ngoes only to the AI tool you already use.\n\n**Can it run unattended or in CI?**\nYes. `/bugsweep --autonomous` runs a find-and-fix loop until the codebase is clean or a\nconfigured limit (time, iterations, or fix count) is hit, re-running your tests after\nevery fix. State persists to disk so long runs survive context resets.\n\n**Does it work with OpenAI Codex too, or just Claude Code?**\nBoth. The installer sets up whichever you have (`--claude`, `--codex`, or `--all`).\n\n## What's inside\n\n- `SKILL.md` — the instructions Claude follows.\n- `scripts/` — the deterministic safety + state layer: `preflight` (branch/stash setup),\n  `run_checks` (tests/build), `guard` (stop conditions), `session` (continuity anchor),\n  `finalize` (safe return). Plus two *optional*, user-owned companions for scheduled runs\n  (outside the trust contract): `bugsweep-prepare.sh` (if the tree is dirty, it defers to an\n  active session or commits genuinely idle work to close the tree — never parks, never\n  discards) and `bugsweep-cleanup.sh` (the post-run merge gate; the only script that merges\n  or deletes, and only when you choose to run it).\n- `prompts/` — the phases, kept separate so the AI never rubber-stamps its own findings:\n  `context-build` (whole-repo model), `research` (anti-pattern priming), `hunt` (local +\n  architectural lenses), `challenge` (Skeptic), `referee` (final arbiter), `fix`.\n- `references/` — safety rationale, the no-tests playbook, tuning notes, the\n  context/continuity model, and `antipatterns/` (the curated per-stack catalogs).\n- `config/bugsweep.config.json` — your settings (caps, excludes, commands, and the\n  adversarial / research / session toggles).\n\nNo third-party dependencies, no network calls (unless you opt into web research), no\ntelemetry. Read `scripts/` and `references/safety-rationale.md` before trusting it — that's\nthe whole point of owning it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshanemhamilton%2Fbugsweep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshanemhamilton%2Fbugsweep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshanemhamilton%2Fbugsweep/lists"}