Patchworks

Patchworks keeps a project connected to the template it came from. It records the exact template commit, then prepares later changes from the template's first-parent history one commit at a time.

This is deliberately different from merging an upstream remote. Your project can diverge freely, and every template update remains a normal working-tree diff or pull request that you review before accepting.

Install

npm install --global patchworks
# or
bun add --global patchworks

Patchworks requires Node.js 18 or newer.

Install the official skill when a coding agent will apply and validate updates:

npx skills add ludicroushq/patchworks --skill patchworks-update

Create a project

patchworks create https://github.com/original/template my-project
cd my-project

To follow a non-default branch:

patchworks create https://github.com/original/template my-project --branch next

The new repository contains two commits:

1. Initial commit, whose tree exactly matches the selected template commit.
2. Configure Patchworks, which adds .patchworks.json and the scheduled GitHub Actions workflow.

The exact-tree setup preserves tracked ignored files, executable modes, binary content, and Git links. Patchworks removes the template remote and reachable history. It refuses to overwrite its reserved files or write through symbolic links, and it only moves the new repository into place after setup succeeds.

Local creation attributes both commits to the effective Git user.name and user.email where the command was invoked. Configure both first; Patchworks fails rather than inventing an identity when either is missing.

Prepare the next update

patchworks update
git status --short
git diff
git diff --cached

The working tree must be clean before the update starts. Patchworks fetches the configured template branch, applies the next first-parent commit with a strict binary-capable patch, advances .patchworks.json, and leaves normal file changes unstaged for plain git diff review.

A Gitlink is the one exception. Submodule pointers have no worktree content, so Patchworks leaves those index entries staged; review them with git diff --cached.

If a patch conflicts, the working tree contains the cleanly applied portions. The complete patch and per-file rejects are collected under .patchworks-rejects/<commit>/. Resolve the code and remove every artifact before committing.

Run patchworks update again after committing to prepare the following template commit.

Automate the review

patchworks create also adds a nightly GitHub Action. It opens one update pull request at a time and skips scheduled runs while that pull request remains open, preserving any human conflict resolutions already pushed to the branch. The generated workflow pins the exact Patchworks v<semver> action release so upgrades are deliberate. Use a GitHub App token or fine-grained PAT when a private template is in another repository, workflow files may change, or the resulting pull request must trigger unattended CI without approval.