pk-sweeper

pk-sweeper is a conservative GitHub issue and pull request maintenance helper. It reviews open items, writes markdown recommendation reports, and can later sync review comments or apply high-confidence decisions only when explicitly requested.

The normal local workflow is safe by default:

cd path/to/target-repo
pksweeper sweep

sweep auto-detects the GitHub repository from the current checkout's origin remote, checks both issues and pull requests with balanced selection, and writes reports without closing, commenting, or merging.

Install

Requires Node.js 24 or newer, the GitHub CLI (gh), and the Codex CLI.

npm install -g pk-sweeper

Or run without installing globally:

npx pk-sweeper sweep

Commands

pksweeper sweep
pksweeper plan
pksweeper quick
pksweeper apply-decisions

sweep is recommended for coding sessions. It runs a preflight before review work starts and prints:

• resolved GitHub repository
• current working directory
• target checkout directory
• output workspace
• Codex CLI path
• target checkout clean/dirty status

If a required check fails, it stops before doing review work.

Target Repository Resolution

PK Sweeper resolves the target repository in this order:

1. --repo <owner>/<repo>
2. PKSWEEPER_TARGET_REPO
3. GH_REPO
4. the current checkout's GitHub origin remote
5. sweeper.config.json targetRepo

For local use, prefer running from the target repo checkout and leave targetRepo as null. Placeholder values such as owner/repo are ignored and reported.

Example config:

{
  "targetRepo": null,
  "docsUrl": null,
  "pluginEcosystem": null,
  "extraStopWords": [],
  "protectedLabels": ["security", "beta-blocker", "release-blocker", "maintainer"]
}

Output

By default, reports are written to a sibling workspace:

../<target-repo>.pksweeper/

Typical files:

• quick-plan.json
• items/<number>.md
• quick-summary.md
• todo.md
• plan.md
• artifacts/reviews/...

Safety

• Review and sweep runs are proposal-only.
• apply-decisions is the command that can mutate GitHub.
• Maintainer-authored items are not auto-closed.
• Protected labels block automated close actions.
• Reviews fail if Codex modifies the target checkout.
• Dirty target checkouts stop preflight unless --allow-dirty is passed.
• Placeholder target repos are ignored instead of queried.

Use --allow-dirty only when local target checkout changes are intentional:

pksweeper sweep --allow-dirty

Examples

Preview candidates:

pksweeper plan

Run a small safe sweep:

pksweeper sweep --agents 2 --concurrency 1 --batch-size 1 --max-pages 2

Run against an explicit repository:

pksweeper sweep --repo octocat/Hello-World

Apply already-reviewed decisions later, after inspection:

pksweeper apply-decisions --limit 5

Do not pass --merge-prs unless you intentionally want high-confidence PR merge proposals to be merged.

Development

npm install
npm run build
npm run check
npm pack

The published package includes only:

• dist
• prompts
• schema
• README.md
• LICENSE

Generated review archives, local workspaces, and target-repo artifacts are not included in the npm package.