Quickstart

Install Patchmill with npm:

npm install -g patchmill

Patchmill needs a working issue-host CLI before it can inspect issues or create pull requests. Set up either GitHub’s gh CLI or Forgejo/Gitea’s tea CLI first; see Providers for details.

In the repository you want Patchmill to manage, initialize the local configuration:

patchmill init

Patchmill writes repository-local configuration, installs recommended skills, and sets up local state.

Triage open issues with your configured workflow:

patchmill triage

Patchmill inspects open issues and applies the configured triage labels and comments.

Advance one ready issue through the production line:

patchmill run-once

A fresh ready issue initializes strict planning state. If the result is review-pending, review and merge the exact planning pull request, then rerun:

# If the result is review-pending, review and merge the exact planning PR.
patchmill run-once --issue N

review-pending exits 0; labels and comments do not approve a fresh phase. A successful implementation ends in an open issue-closing pull request.

Try Patchmill on a disposable demo repository

Before pointing Patchmill at a production repository, create a disposable Team Lunch Poll demo repository and let Patchmill triage its seeded issues.

For GitHub:

patchmill setup-test-repo --provider github-gh --repo OWNER/REPO
gh repo clone OWNER/REPO
cd REPO
patchmill init
patchmill triage
patchmill run-once

For Forgejo or Gitea with a named tea login:

patchmill setup-test-repo --provider forgejo-tea --repo OWNER/REPO --login LOGIN
tea clone OWNER/REPO
cd REPO
patchmill init
patchmill triage
patchmill run-once

Use an explicit disposable public repository for OWNER/REPO. The reset form deletes and recreates that repository:

patchmill setup-test-repo --provider github-gh --repo OWNER/REPO --reset
patchmill setup-test-repo --provider forgejo-tea --repo OWNER/REPO --login LOGIN --reset

Updating Patchmill-managed skills

To update a repository after Patchmill publishes a newer bundled skill pack, run:

npx patchmill@latest skills update

The update command only changes Patchmill-managed project-local skills. It stops if managed skill files were edited locally. Crossing the 2026.09.1 pack boundary prints the planning-pull-request and deprecated-controls notice once; an already-current pack retains the ordinary up-to-date result. After a successful update, run git diff and commit the skill changes with the repository.