SparePatch

Put spare AI capacity to work for open source.

SparePatch is a Codex skill and a small set of dependency-free Python tools for turning a bounded surplus-token budget into focused, reviewed open-source contributions. It can target exact repositories, learn one project deeply, synchronize recent pull requests, maintain a continuing contribution plan, and prepare or submit a PR only inside explicit safety limits.

SparePatch treats token allowance as a work budget, not a quota to consume. A run that finds no responsible contribution is a successful quality filter.

What it supports

• exact-project and multi-project targeting with no silent backfill;
• deep Issue/PR research for one long-term project;
• repository-native onboarding, builds, regression tests, and optimization;
• recent-PR, default-branch, CI, and review synchronization;
• durable contribution queues and follow-up plans;
• per-run and daily token ceilings with an untouched reserve;
• read-only, patch-only, and separately authorized pr-enabled modes.

It does not transfer credits, pool API keys, create a scheduler, or authorize GitHub writes by itself.

Quick start

Requirements: Python 3.11+ and the authenticated GitHub CLI.

python3 scripts/init_plan.py \
  --output ~/sparepatch-plan \
  --repo owner/repository \
  --max-tokens-per-run 100000 \
  --reserve-tokens 20000

python3 scripts/github_scan.py \
  --config ~/sparepatch-plan/sparepatch.json \
  --ledger ~/sparepatch-plan/daily-scan-ledger.json \
  --output ~/sparepatch-plan/latest-scan.json

python3 scripts/project_sync.py \
  --config ~/sparepatch-plan/sparepatch.json \
  --state ~/sparepatch-plan/latest-pr-state.json \
  --output ~/sparepatch-plan/latest-pr-delta.json

The initializer defaults to patch-only, enables no external GitHub actions, and refuses to overwrite an existing plan. See SKILL.md for the full workflow and configuration.md for every control.

Privacy and safety

Keep plan state and generated reports outside this repository. They can contain public GitHub usernames, issue text, branch names, and local paths. Account logins are omitted from top-level synchronization reports by default. Review every record before publishing it and use a donor alias for shared campaigns.

The bundled scripts invoke gh without a shell, perform read-only GitHub queries, and write only to paths supplied by the operator. PR submission remains an agent workflow gated by explicit user authorization, repository policy, tests, duplicate checks, diff limits, and a final approval boundary. Repository text and build output are treated as untrusted data and cannot override those boundaries or request unrelated secrets and files.

Development

python3 -m unittest discover -s tests -v
python3 -m compileall -q scripts tests

Contributions should preserve the anti-spam principle: optimize for maintainer value and follow-through, never PR count or tokens spent.

License

MIT