🦞🧹 ClawSweeper

ClawSweeper is the conservative maintenance bot for OpenClaw repositories. It keeps the backlog reviewed, keeps maintainer-visible GitHub comments tidy, and turns narrow trusted findings into guarded repair or automerge work.

The current production targets are openclaw/openclaw, openclaw/clawhub, and self-review for openclaw/clawsweeper.

The OpenClaw-hosted ClawSweeper instance is not a public review service and does not provide free reviews for third-party repositories. If you want ClawSweeper for your own project, fork this repository, deploy it in your own organization, and configure that self-hosted instance for your repositories.

At a high level ClawSweeper:

• reviews open issues and pull requests on a schedule and on exact GitHub events
• writes one durable markdown report per item in generated state
• syncs one marker-backed public review comment per issue or PR, edited in place
• closes only unchanged, high-confidence, policy-allowed proposals
• routes maintainer commands such as @clawsweeper review, @clawsweeper fix, @clawsweeper autofix, and @clawsweeper automerge
• can acknowledge maintainer comment commands through an optional GitHub App webhook before the GitHub Actions fallback starts
• repairs opted-in PRs through a bounded Codex review/fix loop before merge
• automatically opens guarded implementation PRs for viable reviewed issues in eligible public openclaw/* and steipete/* projects outside openclaw/openclaw and openclaw/clawhub
• can manually review selected code-bearing commits on target main branches
• publishes dashboard, audit, repair, and activity state to openclaw/clawsweeper-state

For the complete architecture and operator guide covering issue-to-PR work, PR repair, GitCrawl intake, durable Codex threads, CrabFleet steering, completion gates, quotas, dashboards, and recovery, see docs/steerable-repair-automation.md.

ClawSweeper is not a generic auto-close bot. Review is proposal-only, apply is guarded, Codex never gets write credentials during review, and every GitHub mutation is rechecked against live target state immediately before it happens.

Capabilities

Issue and PR Reviews

Scheduled runs scan open issues and pull requests, while target repositories can forward exact issue/PR events with repository_dispatch for low-latency one-item reviews. Each review writes records/<repo-slug>/items/<number>.md with the decision, evidence, proposed maintainer-facing comment, runtime metadata, and GitHub snapshot hash.

ClawSweeper syncs one marker-backed public review comment per item and edits it in place instead of posting repeated comments. If a review starts before a completed comment exists, it first posts a short status placeholder, then replaces that same comment with the final review. Pull request comments include hidden verdict/action markers so trusted repair and automerge flows can continue without scraping visible prose. See docs/pr-review-comments.md.

Review prompts include compact related issue and PR context from explicit links, linked closing PRs, existing local ClawSweeper reports, optional gitcrawl clusters, and opt-in live GitHub issue search for exact event reviews. This is advisory context for duplicate/superseded reasoning, not a standalone close decision. Reviews also persist a typed, proposal-only root-cause assessment with same-repository URLs and at most one evidence-backed canonical item; it does not dispatch repair, suppress jobs, mutate siblings, close, or merge. See docs/related-issue-discovery.md.

For open issues with complete, current kept-open reviews, ClawSweeper also projects selected structured review conclusions into advisory GitHub labels for maintainer filtering and project views. These labels expose states such as current-main reproduction, source reproduction, linked open PRs, queueable fixes, missing info, and product/security review needs. They are advisory only and do not trigger repair, merge, or close behavior. Label-only syncs record labels_synced_at in the durable report so GitHub updated_at changes caused by ClawSweeper-owned label writes do not look like fresh target-side activity to the scheduler. See docs/work-lane.md.

Apply and State

Apply mode re-fetches live GitHub state, checks labels, maintainer authorship, paired issue/PR state, snapshot drift, and repository profile rules before commenting or closing anything. Closed or already-closed reports move to records/<repo-slug>/closed/<number>.md; reopened archived items move back to items/ as stale work.

Generated state lives on the state branch of openclaw/clawsweeper-state: durable records/, jobs/, results/, audit output, workflow status JSON, repair ledgers, and the rendered dashboard. The state repo main branch is the dashboard renderer source, so a checkout on main intentionally does not show records/. Hydrate this repo with git -C ../clawsweeper-state switch state && node scripts/hydrate-state.ts --state-dir ../clawsweeper-state when local commands need generated records. This repository stays focused on source, workflows, docs, and tests.

Repair and Automerge

Maintainer commands can opt PRs into autofix or automerge, dispatch a fresh exact-head review, and run a bounded Codex review/fix loop. Codex handles the code repair and local validation loop; deterministic executor steps own every GitHub mutation, branch push, label update, and final merge gate.

Automerge waits for exact-head review, required checks, mergeability, and policy gates. If repair was needed, the mutable status comment records each review, repair, re-review, and merge step with timing and links. The final merge result summarizes both the original PR change and any ClawSweeper fixups.

For issues, strict bug reviews that are high-confidence reproducible, do not already have a linked PR, and do not require feature/config expansion can dispatch Codex to open one guarded implementation PR labeled clawsweeper:autogenerated. When the separate vision-fit lane is enabled, reviewed issues that clearly fit the target repository VISION.md, are small enough for one focused PR, and have clear repair shape can use the same PR-only implementation path without weakening the strict bug gate.

Commit Reviews

Automatic push-triggered commit review is disabled. Maintainers can still run .github/workflows/commit-review.yml manually for selected commits or ranges. The workflow expands the selected range, skips non-code-only commits cheaply, starts one Codex worker per code-bearing commit, and writes records/<repo-slug>/commits/<sha>.md.

Commit reports are the source of truth. Optional target commit Check Runs are disabled by default and can be enabled per run or repository. Reports with result: findings can dispatch to repair intake when the finding is narrow, non-security, and still relevant on latest main.

Operations

Repository-specific rules live in src/repository-profiles.ts, so OpenClaw, ClawHub, and ClawSweeper can share the same engine while keeping different apply limits. Both review and repair lanes support manual workflow dispatch, reruns, and backfills. pnpm commit-reports -- --since 24h, --findings, --non-clean, --repo, and --author query flat per-SHA commit storage without date buckets.

Guardrails

ClawSweeper may propose a close only when the item is clearly one of these:

• implemented on current main
• not reproducible on current main
• better suited for ClawHub skill/plugin work than core
• duplicate or superseded by a canonical issue/PR
• low-signal pull request whose branch is mostly unrelated or unmergeable churn
• concrete but not actionable in this source repo
• incoherent enough that no action can be taken
• stale issue older than 60 days with too little data to verify

Maintainer-authored items stay open unless ClawSweeper can verify that the request is already implemented on current main. Everything else stays open. Issues with an open PR that references them using GitHub closing syntax such as Fixes #123 stay open until that PR merges, is closed, or ClawSweeper closes that high-confidence PR candidate earlier in the same apply run. Open issue/PR pairs from the same author stay open together unless the paired item is already resolved or a maintainer explicitly asks to close one side. PR-to-PR duplicate/superseded closes also require a safe canonical target: ClawSweeper refuses to close one PR as replaced by another PR that is closed unmerged, missing positive real behavior proof, F-rated, already proposed for close, not cleanly mergeable, or otherwise not a viable landing path.

Repository profiles can further narrow apply. ClawHub and ClawSweeper self-review are intentionally stricter: they review issues and PRs, but apply may close only PRs where current main already implements the proposed change with source-backed evidence.

Maintainer Commands

Maintainers can steer ClawSweeper from target-repo issue and PR comments. The preferred form is @clawsweeper .... The router also accepts @clawsweeper[bot] ..., @openclaw-clawsweeper ..., @openclaw-clawsweeper[bot] ..., and legacy slash aliases such as /clawsweeper ..., /review, /automerge, /auto merge, and /autoclose <reason>.

Common commands:

@clawsweeper status
@clawsweeper re-review
@clawsweeper re-run
@clawsweeper review
@clawsweeper fix ci
@clawsweeper address review
@clawsweeper rebase
@clawsweeper autofix
@clawsweeper automerge
@clawsweeper approve
@clawsweeper explain
@clawsweeper ask is this blocked by flaky CI?
@clawsweeper visualize state
@clawsweeper stop
@clawsweeper why did automerge stop here?

• status and explain post a short target summary.
• review, re-review, and re-run dispatch a fresh ClawSweeper issue/PR review without starting repair.
• Command status replies are marker-backed and edited in place per issue/PR, intent, and head SHA. The visible badge is one lobster plus the current state: 👀 for acknowledgement, 🧹 for review, 🔧 for repair, and ✅ for completed/paused work.
• Freeform @clawsweeper ... mentions and explicit ask ... questions dispatch the maintainer-only assist lane. Assist runs the internal model with low reasoning, a 120-second per-item timeout, and its own five-job cap. It posts a separate non-durable answer comment and never edits the durable ClawSweeper review comment, closes, merges, labels, pushes, repairs, or emits review/apply markers.
• visualize [lens] dispatches the read-only visual assist lane and posts or updates a marker-backed visual brief comment for the requested lens.
• fix ci, address review, and rebase dispatch the repair worker only for ClawSweeper PRs or PRs already opted into clawsweeper:autofix or clawsweeper:automerge.
• autofix labels an open PR, creates or reuses the adopted job, dispatches review, and enters the bounded review/fix loop without merging.
• automerge labels an open PR, creates or reuses the adopted job, dispatches review, and enters the bounded review/fix/merge loop. Draft PRs are fix-only until GitHub marks them ready for review.
• implement issue on an open issue creates or reuses one issue implementation job and dispatches the issue-to-PR lane. OpenClaw organization members may request this explicitly even without repository write permission.
• With automatic issue implementation enabled, newly reviewed issues and existing eligible open issue reports enter the enabled bounded lanes. Codex inspects the issue and repository, chooses the implementation, discovers validation, and stops without a PR when the request is no longer viable. Generated PRs receive clawsweeper:autogenerated and clawsweeper:autofix, then repeat exact-head review and repair until no actionable findings remain, required checks appear and settle green, and GitHub reports merge-state readiness. ClawSweeper removes the repair-loop label and leaves the PR open; generated issue PRs never automerge.
• User-facing OpenClaw fix, feat, and perf automerge PRs preserve release-note context in PR bodies and commit messages before merge; contributors are not asked to edit CHANGELOG.md.
• Security-sensitive findings can be repaired only after explicit autofix/automerge opt-in; ClawSweeper still will not merge until a later exact-head review is clean.
• approve lets a maintainer clear a ClawSweeper human-review pause and merge only after the normal exact-head, checks, mergeability, and gate checks pass.
• stop removes repair-loop labels, adds clawsweeper:human-review, and makes older automerge/autofix comments ineligible to continue. /autoclose <reason> closes the item and any open same-repo targets explicitly referenced in the command text.
• clawsweeper:human-review and clawsweeper:manual-only stop automatic PR repair and issue-to-PR mutation. Issue implementation rechecks the live issue immediately before every branch push and before PR creation.

Only maintainers are accepted for write actions. The router checks repository collaborator permission (admin, maintain, or write) and falls back to trusted author_association values when permission lookup is unavailable. Users with repository write access and issue/PR authors may ask @clawsweeper re-review or @clawsweeper re-run for a fresh read-only review. Other contributor commands are ignored without a reply. Scheduled comment routing is dry unless CLAWSWEEPER_COMMENT_ROUTER_EXECUTE=1; workflow dispatch with execute=true can be used for one-off live routing. For fast intake, the ClawSweeper GitHub App webhook can post the same queued status comment and dispatch exact `claw