Clownfish: a conservative GitHub issue and PR cleanup harness for maintainers

What Clownfish does and where it fits in the OpenClaw workflow

Clownfish handles the second pass in a two-step OpenClaw workflow. The first pass is clawsweeper, which scans an entire GitHub backlog on a cadence and groups items into clusters. Clownfish receives those clusters (or clusters assembled by gitcrawl or by hand) and asks a Codex worker to classify each item. Based on the classification, it generates a proposal for what to do: close as a duplicate, close as superseded, close as fixed by a specific PR, or leave open. The default workflow is proposal-first: Clownfish does not comment or close anything unless a job is explicitly promoted by the operator and the deterministic applicator confirms that the live GitHub state has not changed since the classification was made. This guards against acting on stale information.

Allowed automated actions and what stays manual

Clownfish restricts the automated close reasons to three: duplicate of a clear canonical thread, superseded by a clear canonical thread, and fixed by a specific candidate fix. For anything else, it returns needs_human. An optional low-signal PR cleanup policy covers drive-by PRs in specific categories: blank-template submissions, docs-only discoverability churn, test-only coverage spam, refactor-only noise, third-party capabilities that belong on ClawHub, risky unapproved infrastructure changes, and dirty branches. This policy is opt-in per job and must return needs_human for any PR that looks like a plausible bug fix or shows active maintainer engagement. Security-sensitive reports are out of scope. Clownfish routes those to central OpenClaw security handling and continues processing ordinary bugs and duplicates in the same cluster without blocking.

Setting up and configuring Clownfish

Clownfish uses an .env file for configuration. The repository ships an .env.example file with all supported variables:

CLOWNFISH_READ_GH_TOKEN=
CLOWNFISH_GH_TOKEN=
OPENAI_API_KEY=
CLOWNFISH_ALLOWED_OWNER=openclaw
CLOWNFISH_ALLOW_EXECUTE=0
CLOWNFISH_ALLOW_FIX_PR=0

CLOWNFISH_ALLOWED_OWNER restricts which GitHub organization's repositories Clownfish may touch. Setting it before running is important: without it, the tool has no guard on which repositories it can target. CLOWNFISH_ALLOW_EXECUTE defaults to 0, meaning no live mutations happen until explicitly enabled. CLOWNFISH_ALLOW_FIX_PR similarly gates PR merge actions. OPENAI_API_KEY or CODEX_API_KEY authenticates the Codex worker that classifies items in a cluster. Additional variables control hydration: CLOWNFISH_HYDRATE_CLUSTER_REFS and CLOWNFISH_HYDRATE_COMMENTS control whether cluster issue references and issue comments are fetched from GitHub during classification. CLOWNFISH_MAX_COMMENTS_PER_ITEM, CLOWNFISH_MAX_LINKED_REFS, and CLOWNFISH_MAX_REVIEW_COMMENTS_PER_PR cap how much data is pulled per item to keep API calls and token usage bounded. CLOWNFISH_CODEX_REVIEW_ATTEMPTS sets how many classification retries the Codex worker makes before giving up.

Job structure and the plan-cluster workflow

Jobs are Markdown files stored under the jobs/ directory, one per cluster. A cluster comes from gitcrawl via the import-gitcrawl script, from the import-github-pr-inventory or import-github-low-signal scripts, or from a manually assembled list. The package.json lists the main workflow scripts: create-job creates a new job file, plan-cluster generates an action proposal by running the Codex worker against the cluster, apply-result applies a reviewed proposal to GitHub, assert-mutation-integrity checks that the live state still matches the proposal before applying, and execute-fix runs a specific fix artifact. The validate and validate:job scripts check that job files conform to the JSON schema in the schemas/ directory. Results land in the results/ directory as Markdown files named after the cluster, one per cluster. The promote-stuck-jobs script handles clusters that have stalled in a waiting state, and sweep-openclaw-jobs runs the full sweep across the OpenClaw organization's job inbox. The comment-router script routes new GitHub comments to the appropriate cluster handler.

Dashboard metrics and current operational state

The README embeds a dashboard block that was last updated on June 16, 2026. At that point, 4,178 active cluster reports were tracked. Of those, 2,722 were completed cleanly (65.2 percent), 1,188 needed human review (28.4 percent), and 99 had failed (2.4 percent). Fix action attempts stood at 316, with 2 executed, 68 failed, and 115 blocked. The high blocked rate reflects the deterministic applicator checking live GitHub state before any mutation: if the state changed between classification and application, the action is blocked rather than applied blindly. The close actions completed so far broke down as 25 duplicate closes, 22 superseded closes, and 15 fixed-by-candidate closes. These numbers represent the openclaw organization's own use of the tool; they are audit data embedded in the README, not guarantees of performance on other repositories.

Compared to clawsweeper and manual triage

Clownfish is intentionally smaller in scope than clawsweeper. The README states the distinction explicitly: ClawSweeper scans the full OpenClaw backlog on a cadence and groups similar items; Clownfish handles targeted clusters that were already grouped by a human, gitcrawl, or another deduplication tool. The two are designed to run in sequence, not as alternatives. The alternative to this pair is manual triage: a maintainer reads each issue or PR, decides whether it is a duplicate, superseded, or fixed, and closes or merges by hand. Manual triage gives the highest accuracy but does not scale to thousands of open items. Clownfish trades breadth for precision: it handles only the clusters given to it and only acts when the Codex classification crosses the confidence threshold, leaving everything ambiguous for the maintainer to handle. The result is a smaller, more reliable action surface than a fully automated tool would produce. The dashboard data shows this in practice: of 316 fix action attempts, only 2 were executed, 68 failed, and 115 were blocked by the mutation integrity check.

Editorial conclusion

Clownfish is the right tool for maintainers who receive curated issue clusters from clawsweeper or gitcrawl and need a reproducible, proposal-first cleanup that only acts when the classification is unambiguous. It is not a replacement for manual review: the dashboard shows 28.4 percent of latest clusters in needs-human state, meaning more than a quarter of clusters require a maintainer decision before Clownfish can proceed. Before deploying, set CLOWNFISH_ALLOWED_OWNER to your organization and confirm CLOWNFISH_ALLOW_EXECUTE=1 only in environments where you intend live mutations to take effect.

Frequently asked questions

Official sources

1. Official README
2. Project repository