{"id":50522237,"url":"https://github.com/thrillmade/clud-bug","last_synced_at":"2026-06-03T05:04:10.689Z","repository":{"id":343636000,"uuid":"1178519421","full_name":"thrillmade/clud-bug","owner":"thrillmade","description":"Claude PR review with project-aware skills. Encode your team standards (brand voice, API contracts, compliance, test discipline) as Markdown skills the bot cites by name on every PR. One-command install: npx clud-bug init.","archived":false,"fork":false,"pushed_at":"2026-05-27T02:02:19.000Z","size":377,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T03:26:55.188Z","etag":null,"topics":["ai-code-review","claude","claude-code","cli","code-review","github-actions","npm-package","pr-review","pull-request","skills","skills-sh"],"latest_commit_sha":null,"homepage":"https://cludbug.dev","language":"JavaScript","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/thrillmade.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-11T05:14:54.000Z","updated_at":"2026-05-27T02:02:22.000Z","dependencies_parsed_at":"2026-05-26T17:03:31.843Z","dependency_job_id":null,"html_url":"https://github.com/thrillmade/clud-bug","commit_stats":null,"previous_names":["thrillmot/clud-bug","thrillmade/clud-bug"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/thrillmade/clud-bug","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Fclud-bug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Fclud-bug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Fclud-bug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Fclud-bug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thrillmade","download_url":"https://codeload.github.com/thrillmade/clud-bug/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thrillmade%2Fclud-bug/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33848882,"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-06-03T02:00:06.370Z","response_time":59,"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":["ai-code-review","claude","claude-code","cli","code-review","github-actions","npm-package","pr-review","pull-request","skills","skills-sh"],"created_at":"2026-06-03T05:04:10.019Z","updated_at":"2026-06-03T05:04:10.680Z","avatar_url":"https://github.com/thrillmade.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clud Bug 🐛\n### A field guide to specimens crawling your code\n\n\u003e **[cludbug.dev](https://cludbug.dev)** · live field journal.\n\nClud Bug is **skill-driven PR review** for your GitHub repo. Ship a brand-voice skill, get brand reviews. Ship a compliance skill, get PII checks on every diff. Each finding cites the skill that motivated it — the bot's authority comes from your specimens, not from generic advice.\n\nFour baseline skills ship by default — covering bug-finding, evidence-based review discipline, pattern conformity, and agent coordination. Add more from [skills.sh](https://skills.sh) or write your own — the bot loads them automatically.\n\nOne command to install. The first PR you open afterwards gets a real review back — typically within two minutes.\n\n## Quickstart\n\n```bash\ncd your-repo\nnpx clud-bug init\ngit add .claude .github/workflows/clud-bug-review.yml\ngit commit -m \"Add clud-bug PR review\"\ngit push\n\n# OR — install the full SkDD toolchain (clud-bug + logmind) in one go:\nnpx clud-bug init --with-skdd   # subprocesses to `pip install logmind \u0026\u0026 logmind init`\n```\n\nThen in your repo on GitHub:\n**Settings → Secrets and variables → Actions → New repository secret** → set `ANTHROPIC_API_KEY`.\n\nOpen a PR. A review comment should appear within ~2 minutes.\n\n## What `clud-bug init` does\n\nThe naturalist arrives at your repo, surveys the habitat, and assembles a field kit:\n\n1. **Surveys habitat.** Reads `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., to learn what your stack is.\n2. **Consults [skills.sh](https://skills.sh).** Pulls review skills relevant to your dependencies (e.g. a Next.js project gets Next.js review specimens).\n3. **Pins baseline specimens** that enforce review discipline regardless of stack:\n   - `critical-issues-only` — flag bugs, security, perf only. Skip nits.\n   - `evidence-based-review` — every claim must quote the line being criticized.\n   - `respect-existing-conventions` — don't suggest fights with the codebase's patterns.\n   - `clud-bug-collaboration` — guidance for any other Claude Code agents working in your repo: how to coexist with bot review threads, how to read the gate, why workflow self-mods break the action, etc.\n4. **Writes** the chosen specimens to `.claude/skills/\u003cname\u003e/SKILL.md` (Claude Code auto-loads them in the GitHub Action).\n5. **Drafts the field kit** at `.github/workflows/clud-bug-review.yml` with your project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually post.\n6. **Briefs other agents** by adding a `\u003c!-- clud-bug-start --\u003e` block to `AGENTS.md` (creating it if missing — it's the cross-tool canonical), and idempotently to `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`, `.continuerules`, and `.cursor/rules/*.md` where they already exist. Re-runs replace the prior block in place. Files you didn't already have are left uncreated — no proliferating stubs.\n7. **Offers to enable `required_conversation_resolution`** on your default branch. Clud Bug auto-resolves its own review threads when fixes land — but that only gates merges when conversation-resolution is required. Init detects the current state via `gh`, prompts to enable (auto-yes with `--accept-all`), and degrades to an advisory message if you lack admin perms / `gh` isn't installed / the branch has no base protection rule. Pass `--no-set-protection` to skip the prompt entirely — for repos that manage branch protection via ruleset or org policy.\n\n## CLI options\n\n```\nnpx clud-bug init [options]\n\n  --offline             Skip skills.sh; install only the bundled baseline skills.\n  --accept-all,-y       Accept the recommended skill set (and the\n                        branch-protection prompt) without prompting.\n  --no-set-protection   Skip the prompt that offers to enable\n                        required_conversation_resolution on the default\n                        branch. For repos that manage branch protection\n                        via ruleset or org policy.\n  --commit              git add + commit the generated files when done.\n  --help,-h             Show help.\n```\n\n## Staying up to date\n\n`clud-bug init` ships a third workflow: `clud-bug-self-update.yml`. Once a week (Mondays 12:00 UTC), it checks npm for a newer `clud-bug` version. If one exists, it runs `clud-bug update` and opens a PR titled `🐛 Clud Bug self-update: vX.Y.Z → vA.B.C`. Custom and skills.sh-installed specimens are never touched — only baseline specimens and the workflow templates get refreshed.\n\nYou can also run the update manually:\n\n```bash\nclud-bug update\n```\n\nTo pin a specific version and stop receiving update PRs, add `pinVersion` to `.claude/skills/.clud-bug.json`:\n\n```json\n{ \"pinVersion\": \"0.3.0\", ... }\n```\n\n## Auditing the whole repo\n\nPR reviews catch issues entering. Audits catch issues that already crossed the line.\n\n```bash\nclud-bug audit                      # walk every tracked file\nclud-bug audit --changed-in 7d      # only files touched in the last 7 days\nclud-bug audit --since 2026-01-01   # only files touched since a date\nclud-bug audit --scope 'src/**/*.ts'  # narrow by glob (repeatable)\n```\n\nThe CLI prepares an `audits/YYYY-MM-DD.md` stub. For findings, `clud-bug init` also installed `.github/workflows/clud-bug-audit.yml` — go to **Actions → Clud Bug 🐛 Audit → Run workflow**. Clud Bug walks the manifest, appends findings to the same file, opens a PR you can read, act on, then merge or close.\n\nThe workflow ships with `workflow_dispatch` only (manual). The cron is in the file, commented — uncomment for weekly audits.\n\n## Strict mode (default since v0.4.0)\n\nClud Bug runs in **strict mode by default** for new installs. The workflow check fails when Clud Bug flags a critical issue (bug, security, performance, missing test coverage) — green means clean, red means the bot found something to address. Add `clud-bug-review` to your branch protection's required status checks and merging is blocked until findings are addressed.\n\n`clud-bug init` writes `{ \"strictMode\": true }` to `.claude/skills/.clud-bug.json`. To opt out into advisory mode (the bot still reviews; the check stays green regardless of findings), set `strictMode: false`:\n\n```json\n{ \"strictMode\": false, ... }\n```\n\nThe toggle takes effect on PRs opened *after* the new value lands on the base branch (the gate reads the manifest from the base ref so PRs can't disable strict on themselves).\n\n**Existing installs upgrading to v0.4.0:** the new default only fires on fresh installs (manifests that have never been touched by `init` or `update`). Existing repos — including v0.3.x advisory installs that never set `strictMode` — keep their prior behavior on re-init. To enable strict mode in an existing repo, add `\"strictMode\": true` to `.claude/skills/.clud-bug.json` manually.\n\n## Bot-authored PRs (Dependabot, Renovate, fork PRs)\n\nGitHub deliberately doesn't pass repository secrets to workflows triggered by bot-authored PRs (`dependabot[bot]`, `renovate[bot]`) or PRs from forks. The action can't authenticate against Anthropic, so Clud Bug can't review.\n\nRather than failing red (wrong signal), the workflow detects this case, posts a one-line advisory comment to the PR explaining the skip, and exits 0. The check stays green; the comment makes the skip visible. Reviews are your responsibility on those PRs.\n\nTo enable real reviews on Dependabot PRs, [add ANTHROPIC_API_KEY to Dependabot's secret scope](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot).\n\n## How skills shape reviews\n\nSkills aren't background reading material for the bot — they're rules with authority. The workflow prompt now requires Clud Bug to:\n\n1. **Cite the skill by name** when applying its guidance: e.g. `[evidence-based-review]: this claim isn't anchored to a line`.\n2. **End every review with a footer** listing which skills shaped the findings: `Skills referenced: [critical-issues-only, next-best-practices, my-team-rules]`.\n\nThe footer is your audit trail. If a review's footer is `[none]`, either the bot found nothing relevant in your installed skills (and should explain why), or your skill set isn't covering the kinds of changes you actually ship — a signal to add or write new specimens.\n\n`clud-bug init` warns when it would install only baseline specimens. Pair with at least one project-aware skill from skills.sh, or your own — that's where the wedge over stock Claude review comes from.\n\n## Managing skills\n\nAfter `init`, four commands let you evolve the skill set without re-running the whole setup:\n\n```bash\nclud-bug list                                       # show what's installed\nclud-bug add vercel-labs/skills/next-best-practices # install one from skills.sh\nclud-bug remove next-best-practices                 # uninstall (refuses custom skills)\nclud-bug refresh                                    # re-query skills.sh, diff vs installed\n```\n\nSkills are tracked in `.claude/skills/.clud-bug.json` (a small manifest). Anything in `.claude/skills/` that *isn't* in the manifest is treated as your custom work and never modified by `clud-bug` commands.\n\n## Adding your own skills\n\nDrop any `.md` file into `.claude/skills/\u003cyour-skill\u003e/SKILL.md` — Claude Code auto-discovers it on the next PR. Same format as skills from skills.sh:\n\n```markdown\n---\nname: my-team-rules\ndescription: One-line description of what this skill teaches the reviewer.\n---\n\n# My team rules\n\nRules go here. Be specific, cite examples, explain the why.\n```\n\nThis is how you encode your team's PR-review discipline (e.g. \"always check for SQL injection in `db/queries/`\", \"API responses must include error codes from `lib/errors.ts`\").\n\n## Why this works (and why the original `claude-code-action` install often doesn't)\n\n`anthropics/claude-code-action@v1` is the underlying engine — clud-bug just configures it correctly. Two things people commonly miss when wiring it themselves:\n\n- **`gh pr comment` is disabled by default.** Without `--allowedTools` whitelisting it, Claude runs, thinks, and exits silently. clud-bug's generated workflow includes the right allowlist.\n- **Skills are not auto-loaded from anywhere.** If you don't ship `.claude/skills/*` in your repo, Claude reviews with zero project context. clud-bug installs a curated set so the review is actually project-aware.\n\n## Fork PR caveat ⚠️\n\nGitHub does **not** pass repo secrets (including `ANTHROPIC_API_KEY`) to workflows triggered by PRs from forks. By default, `pull_request` workflows on fork PRs will run with no API key and produce no comment.\n\nIf you want clud-bug to review fork PRs too, you have two options:\n\n1. **Maintainer re-pushes the branch** to your repo as a non-fork branch, and the review runs.\n2. **Switch the trigger to `pull_request_target`** (advanced) — this gives the workflow access to secrets but runs against the *base* ref, not the PR's code. To safely review the PR's actual code, follow [`anthropics/claude-code-action` security.md](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md): check out the PR head into a **subdirectory** (not the workspace root) and pass it via `--add-dir`. Skipping this is a code-execution risk.\n\nConcretely, the safe shape:\n\n```yaml\non:\n  pull_request_target:\n    types: [opened, synchronize]\n\njobs:\n  clud-bug-review:\n    steps:\n      - uses: actions/checkout@v6  # base ref — trusted\n      - uses: actions/checkout@v6  # PR head — UNTRUSTED, into a subdir\n        with:\n          ref: ${{ github.event.pull_request.head.sha }}\n          path: pr-head\n      - uses: anthropics/claude-code-action@v1\n        with:\n          claude_args: --add-dir pr-head\n          # ... rest of args\n```\n\nThe key invariant: the base checkout (with secrets in scope) lives at the workspace root; the PR head (untrusted user code) only ever lives in a subdirectory the action explicitly opts into via `--add-dir`. Any deviation — checking out the PR head at the root, running `npm install` from the subdir, etc. — re-opens the code-execution risk.\n\nclud-bug's generated workflow uses `pull_request` (not `pull_request_target`) by default. If you understand the trade-offs and want to handle fork PRs, edit the trigger yourself using the shape above.\n\n## When you edit the workflow\n\n\u003e **TL;DR:** if you see `App token exchange failed: Workflow validation failed (401)` on a PR that edits a clud-bug workflow file, that's **expected and protective** — not a bug in your PR. Read on.\n\nclud-bug uses [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action), which **refuses to run when the PR being reviewed modifies the action's own workflow file**. That's a security guard: without it, a PR could neuter the reviewer or exfiltrate secrets via prompt injection in the workflow file itself.\n\n### What you'll see\n\nWhen you push a PR that touches `.github/workflows/clud-bug-review.yml` (or any other clud-bug workflow):\n\n- The `clud-bug-review` check fails with `App token exchange failed: 401 Unauthorized — Workflow validation failed. The workflow file must exist and have identical content to the version on the repository's default branch.`\n- You'll get a GitHub email titled something like **\"[thrillmade/your-repo] Run failed: Clud Bug 🐛 Crawls Your Code — `\u003cbranch-name\u003e`\"** — same wording for every workflow failure, so it doesn't visually distinguish \"this is the expected self-mod guard\" from \"real failure.\"\n\n### How to merge\n\nIf the PR contains **only** workflow edits, this is the expected path:\n\n1. A maintainer reviews the diff directly (the bot can't).\n2. Merge via admin override (`gh pr merge --admin` or the \"Merge without waiting for requirements\" button) — the failing `clud-bug-review` check is the bot refusing to review *itself*, not a real defect.\n3. Subsequent PRs on the new workflow work normally — the validation gate compares against `main`, so once your edit is on `main`, the gate passes.\n\nIf the PR contains workflow edits **mixed with other code changes**, split them. The bot can't review either half while the workflow edit is in the diff, so any real findings get masked.\n\n### The helper command\n\n`clud-bug edit-workflow` packages the workflow change into a clean PR for you, refusing to run if your working tree has any non-workflow changes:\n\n```bash\n# Edit .github/workflows/clud-bug-*.yml as you like, then:\nclud-bug edit-workflow\n```\n\nThis keeps the merge ceremony scoped to just the workflow edit.\n\n## Verifying it works\n\nAfter install:\n\n1. Confirm `ANTHROPIC_API_KEY` secret is set on the repo.\n2. Open a throwaway PR with an obvious bug (e.g. `const x = null; x.foo()`).\n3. Within ~2 min, Clud Bug should post a comment flagging it.\n4. If no comment: check the **Actions** tab logs. Look for `gh pr comment` invocations and any \"Resource not accessible by integration\" errors (usually a permissions issue or a fork PR).\n\n### Reading a review\n\nEvery Clud Bug review opens with a status line that tells you exactly what changed since the previous pass — particularly useful on re-review after you push a fix:\n\n```\n## 🐛 Clud Bug review\n\n**This round:** 0 critical · 1 minor · 3 resolved from prior · 0 still open\n\n### Findings\n…\n```\n\n- **critical** — new critical findings in this review (these are what strict mode gates on)\n- **minor** — non-critical findings (suggestions / nits)\n- **resolved from prior** — prior unresolved threads the bot just cleared because it verified your fix in the diff\n- **still open** — prior threads whose issue is still standing\n\nSame format every time; zero values are always present so the line is easy to scan and parse.\n\n## Manual install (advanced)\n\nIf you don't want to use the CLI, you can install a generic workflow by hand:\n\n```bash\nmkdir -p .github/workflows\ncurl -o .github/workflows/clud-bug-review.yml \\\n  https://raw.githubusercontent.com/thrillmade/clud-bug/main/templates/workflow.yml.tmpl\n# Edit {{PROJECT_DESCRIPTION}} and {{LANGUAGE_HINTS}} placeholders by hand.\n```\n\nThe CLI does this for you, plus skill curation.\n\n## Contributing\n\nPull requests welcome. If you're adding a new detector for a language ecosystem, put it in `lib/detect.js` and add a fixture-based test in `test/detect.test.js`.\n\n```bash\nnpm test          # node:test, no runtime deps\n```\n\n## License\n\nMIT.\n\n---\n\n## Part of the thrillmade SkDD toolchain\n\n[Skills-Driven Development](https://zakelfassi.com/skdd-skills-driven-development) (Zak Elfassi's methodology) gives you the loop; the thrillmade toolchain ships the parts:\n\n- **[logmind](https://github.com/thrillmade/logmind)** — the *why* behind every change (decision logging as commit primitive); skill-creation + testing + auditing\n- **[clud-bug](https://github.com/thrillmade/clud-bug)** — skill-driven PR review at gate time; every finding cites the skill that motivated it\n- **[agent-skills](https://github.com/thrillmade/agent-skills)** — public catalog of reusable skills\n- **[skills.sh](https://skills.sh)** — skill discovery + install\n\nEnd-to-end agentic auto dev: write skills first → log the *why* → run them against PRs → iterate based on usage. The tools work independently; better together.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrillmade%2Fclud-bug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthrillmade%2Fclud-bug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthrillmade%2Fclud-bug/lists"}