syncwheel
v0.18 — reconcile · resume · ledger

One branch.Many PRs.

Hack in one place. Syncwheel rebuilds, reconciles, and publishes every PR branch from one declared manifest.

Get started Read the docs
How syncwheel works You commit on one working branch. The syncwheel manifest, shown as the syncwheel logo, projects that work into three clean pr branches that are pushed to the remote, while upstream keeps moving. upstream/main main-integration where you work · all PRs together .syncwheel/manifest.json pr/feature-a pr/feature-b pr/hotfix-c ! ! origin

You work in one place. Syncwheel projects it into clean PRs.

Stop remembering. Start declaring.

? ? force-pushed? ???
By handDrifted PRs, mystery commits, tribal knowledge.
= every PR, in order rebuilt
With syncwheelDeclared stacks, rebuildable branches, one truth.

Seven moves. One wheel.

Three to set up, four that loop forever — click through, or just watch.

manifest upstream/main pr/feature-a pr/feature-b pr/feature-c main-integration · every PR in one branch origin existing PR · adopted existing PR · adopted created by syncwheel replayed in manifest order absorb · to the PR that owns it ! ! plan: 2 branches drifted · nothing mutated backup/pr-feature-a-before-syncwheel new base worktree ../wt/pr-feature-a worktree ../wt/pr-feature-b --force-with-lease second device · agent ledger
$ syncwheel stack sync feature-a $ syncwheel stack create feature-c

Two PRs existed already — declare them in the manifest. The third is born managed.

$ syncwheel int rebuild

Every declared commit lands in one integration branch — grouped stack by stack, in manifest order.

$ syncwheel stack absorb feature-b --staged

New work lands on integration first — absorb sends each change to the PR that owns it, file by file or hunk by hunk.

$ syncwheel reconcile

Dry-run: compare manifest, branches, and remote tips. Nothing mutates.

$ syncwheel sync --worktree-root ../wt

Same changes, new commits: each drifted branch is replayed onto the new base — in a worktree, backup first.

$ syncwheel publish --worktree-root ../wt

Push managed branches with --force-with-lease.

$ syncwheel resume

Another device or agent worked? Converge from the ledger.

Four ideas. No magic.

Manifest is the lens

One JSON file declares which commits belong to which PR.

Integration is disposable

Test everything together. Throw it away. Rebuild it identically.

Absorb sorts your hacking

Edits on integration get assigned — per file or per hunk — to their stack.

The ledger remembers

Append-only history. Any machine resumes where the last stopped.

Built for AI agents: no checkout is authoritative — agents follow the manifest, not memory.

Agent contract → Agent procedure →

Go deeper.

Everything advanced lives in the docs.

README Quick start and CLI summary. Workflow model Stacks, manifest, integration, lifecycle. Deterministic model Manifest semantics and validation contract. Branch model Branch roles and safety defaults. Core procedure Deterministic recovery, step by step. Manual Git flow The raw Git equivalent. AI agents Behavior contract and agent procedure. The article The narrative version, for everyone.

Get started

Python 3.11+, Git, uv.

1 · install 
$ uv tool install "git+https://github.com/NestDevLab/syncwheel"
$ syncwheel --help
# developing syncwheel itself? `uv tool install --editable /path/to/syncwheel`
2 · your first wheel 
$ syncwheel init                               # writes .syncwheel/manifest.json
$ syncwheel stack create feature-a --branch pr/feature-a -u  # --include-in-integration
$ syncwheel stack set feature-a origin/main..HEAD
$ syncwheel reconcile                          # dry-run plan first, always
$ syncwheel sync --worktree-root ../wt
$ syncwheel publish --worktree-root ../wt

Shorthands (rec, s, i, -p, -u), repo aliases, and self update live in the README.