🐠 Project Clownfish

ProjectClownfish is a conservative OpenClaw maintainer tool for one-cluster issue and PR cleanup.

It takes a curated GitHub issue/PR cluster, asks a Codex worker to classify the items, and applies only narrow, auditable cleanup actions when the evidence is strong. This compliments the pre-pass work on clawsweeper and act as the second-pass intent based cluster resolution.

Allowed automated close reasons:

• duplicate of a clear canonical thread
• superseded by a clear canonical thread
• fixed by a specific candidate fix

Everything else stays open or is escalated for maintainer review.

Status

ProjectClownfish is intentionally smaller than ClawSweeper. ClawSweeper scans the whole OpenClaw backlog on a cadence; ProjectClownfish handles targeted clusters that were already grouped by a human, ghcrawl, or another dedupe tool.

Cluster discovery currently comes from vincentkoc/ghcrawl. That repository is expected to migrate into the OpenClaw organization soon.

The default workflow is proposal-first. It does not comment or close unless a job is explicitly promoted and the deterministic applicator confirms live GitHub state has not changed.

How It Works

Each cluster job:

1. Starts from one markdown job file under jobs/.
2. Hydrates the listed issue/PR refs and first-hop linked refs.
3. Builds a cluster plan and fix artifact for autonomous jobs.
4. Runs Codex with repo-local policy prompts and JSON output schema in a read-only sandbox.
5. Writes structured run artifacts under .projectclownfish/runs/.
6. Reviews the worker artifact with deterministic safety checks.
7. Applies only safe close/comment actions through scripts/apply-result.mjs.

Codex does not receive a GitHub token. The runner preflights GitHub state before model execution, then Codex receives those artifacts and returns JSON only. The applicator re-fetches the target item, checks updated_at, blocks maintainer-authored items, writes an idempotent close comment, and closes only supported duplicate/superseded/fixed-by-candidate actions.

Runs for the same job path and mode are queued instead of running concurrently. The workflow uses Node 24 and ubuntu-latest for ClawSweeper parity; other hosted runners are opt-in.

Modes

plan produces recommendations only.

execute can apply reviewed safe close actions from structured JSON.

autonomous adds live cluster preflight and fix-artifact generation. It may recommend a canonical fix path, but direct mutation still goes through the applicator.

Any unclear canonical choice, stale cluster state, failing checks, conflict, broad fix, or independent report should become needs_human.

Autonomous PR work must also clear automated reviewer feedback. Greptile, Codex, Asile, CodeRabbit, Copilot, and similar bot comments must be addressed, proven non-actionable, or escalated before any merge or post-merge closeout recommendation.

Local Run

Requires Node 24.

Validate jobs:

npm run validate

Render a prompt:

npm run render -- jobs/openclaw/cluster-example.md --mode plan

Dry-run a worker without calling Codex:

npm run worker -- jobs/openclaw/cluster-example.md --mode plan --dry-run

Build an offline autonomous artifact:

npm run build-fix-artifact -- jobs/openclaw/autonomous-example.md --offline

Checks

npm run validate
for f in scripts/*.mjs; do node --check "$f" || exit 1; done
npm run review-results -- .projectclownfish/runs
git diff --check

GitHub Actions Setup

The workflow needs:

• Codex/OpenAI authentication for model execution
• a read-only GitHub token for worker inspection
• a separate write-scoped GitHub token for the deterministic applicator
• an execution gate that defaults off

Keep exact secret names, token scopes, and execution-window procedures in private operations docs or repository settings notes. Do not put token values or live operational credentials in job files.