Keep many long-lived pull requests clean, rebuildable, and publishable from one manifest.
Current version: 0.47.23
syncwheel is a small CLI and workflow model for maintainers who carry several
PR branches against an upstream repository and need those branches to stay
under control over time.
It is especially useful when you:
- keep many open PRs alive while upstream keeps moving
- maintain a fork with clean review branches and a combined local runtime branch
- need to rebuild PR branches deterministically instead of hand-rebasing them
- want to send several pull requests while working in a single checkout, without a worktree per branch
- need to own a commit before you know which pull request it belongs to
- need a repeatable branch that combines selected feature stacks for a shared or temporary deployment flow
- work across multiple devices or AI agents without one checkout becoming the hidden source of truth
- want branch recovery to follow a manifest, not memory
integration/* is recommended, not mandatory.
You can use syncwheel in two modes:
- PR-only mode: manage and validate PR stacks without an integration branch
- Integration mode: also maintain a combined branch to test multiple in-flight PRs together
Git can tell you what happened. It cannot reliably tell you which commits belong
to logical PR feature-a, which commits are temporary integration-only work,
or how to rebuild ten open PRs after upstream changed.
Syncwheel adds that missing control plane:
- one manifest declares commit ownership
- each stack maps to one PR branch
- integration is a disposable projection of the manifest
- a rebuild restores and records a deterministic, manifest-only control commit
when its projected tree carries an older manifest;
int rebuild --reasonis required forai-managedrepositories - deployment channels pin selected stack revisions into ordered, rebuildable branch compositions
reconcilecompares local branches, remote tips, and manifest projections- humans, scripts, and AI agents can all run the same lifecycle
The practical result is that a maintainer can keep many PRs open without turning branch history into tribal knowledge.
python3 scripts/syncwheel.py repo tracking status
python3 scripts/syncwheel.py reconcile
python3 scripts/syncwheel.py resume
python3 scripts/syncwheel.py sync
python3 scripts/syncwheel.py publishDefault behavior is conservative:
reconcileis the dry-run diagnostic entrypointcheck --strictis the CI/readiness gate: warnings, undeclared stack-branch commits, or any planned action produce a non-zero exitresumeis the dry-run recovery entrypoint for cross-device resume when integration contains unmapped commits that can be classified deterministicallyledger showexposes Syncwheel's append-only event ledger and the current replayed state used for cross-machine recoverysyncapplies the safe local lifecycle without pushingpublishapplies the lifecycle and pushes managed branches- lower-level
reconcile --applyandreconcile --apply --pushremain available for explicit scripting - legacy manifests use
--force-with-leaseby default, because managed branches are often rewritten by deterministic rebuilds; for stack branches the lease is pinned to the live remote tip, and the push stops when that tip holds a commit the stack does not own, so another session's pushed work is not discarded (integration pushes keep the plain lease) - active-active version 2 or 3 manifests publish managed refs and state together with atomic, exact leases; unsupported remotes fail closed
- once coordination state is published, a new managed branch (stack, channel or promotion target) is never published onto an existing remote branch the state does not manage; such a branch stops the push
- the first coordinated publication only moves an existing remote branch
forward; if the remote holds commits the local tip lacks, it stops and names
the tip, and
int push --adopt-remote <tip>replaces exactly that tip once nothing on it may be lost - public coordination state uses typed canonical and publication remote roles, rejects ambiguous aliases that cannot be normalized safely, and makes a reused managed branch immediately supersede its old cleanup tombstone
repo tracking statusshows whether the manifest isgit-tracked,local-only, or missing a persisted policy- if a remote managed branch already matches the manifest projection,
sync,publish, andreconcile --applyalign the local branch to that remote instead of rebuilding new replacement commits - pass
--no-align-local-to-remotewhen you intentionally want to preserve a different local history for manual inspection
For legacy manifests, use --no-force-with-lease only when a normal push is
intentionally required.
To publish without removing a captured validation copy, explicitly retain it:
git worktree lock --reason "Keep validated source for inspection" <captured-worktree>
syncwheel stack push feature-a --retain-captured-worktrees "Keep validation evidence"A retained captured copy must have completed native capture and remain locked. A clean, registered active lane at the exact declared tip can also be published with or without the retention option. Both forms preserve the active lane. Every lane used as a source must have the exact publication HEAD, no tracked or untracked changes, and no interrupted cleanup. All its commits must belong to the selected stack. Syncwheel rechecks these proofs before publication. Legacy pushes pin that HEAD in the refspec. The Git lock protects against cleanup, not subsequent edits; publication uses the commit, not the copy's mutable files. The default recovery requirement and destructive-operation guards remain unchanged.
Use stack history adoption to declare an existing merge graph and publish its exact reviewed tip.
Further committed corrections to an already captured copy can be recaptured without cleanup using the same explicit option:
syncwheel stack capture-integration feature-a <commit-or-range> --retain-captured-worktrees "Keep validation evidence"The proposed complete stack history must be contiguous, single-parent history on the selected stack base and end exactly at the retained HEAD. Unrelated or missing commits fail before ownership changes. Capture rechecks the copy before changing refs and verifies the resulting publication HEAD without reaping any retained copy.
syncwheel_tracking=git-tracked means .syncwheel/manifest.json should be
tracked by Git. syncwheel_tracking=local-only keeps Syncwheel metadata local
through .git/info/exclude: without active-active coordination the integration
branch gets no control commit, and no Syncwheel push carries the manifest to a
stack, pull-request or delivery branch. New managed worktrees default to repo-relative
.syncwheel/wt/.
With a personal manifest selected, repo tracking set changes only that manifest's
policy and private ledger. Both tracking values leave shared ignore files, hooks,
the manifest README and Git indexes unchanged. Personal metadata must already be
ignored and untracked; changing its policy does not migrate the shared repository.
The command prepares the manifest and ledger update before publication and restores
its own writes if publication raises a handled error. This rollback does not
provide automatic recovery from process termination or power loss.
authority declares how far agents may take a change on their own. A repo
with mode=ai-managed and source_change allowed lets an agent edit, test,
commit, push, open and merge the PR without asking at each step; runtime_change
must be granted separately; destructive_rewrite can never be granted. An
absent block in the primary shared manifest means human-gated. A lane or
personal manifest without its own block inherits that primary policy. An explicit
lane declaration may retain or restrict its grants, never widen them. Inspect and set it with
syncwheel repo authority status and syncwheel repo authority set.
Manifest versions 2 and 3 can safely coordinate the same integration branch from
multiple independent devices or agents. New git-tracked manifests enable it
when their publication remote is configured:
syncwheel init --syncwheel-tracking git-tracked --publication-remote origin
syncwheel handoff
syncwheel publishExisting version 1 manifests remain legacy. Upgrade deliberately with
syncwheel coordination init --remote origin --apply; opt out with
syncwheel coordination disable --apply. Active coordination requires atomic
push support and never falls back to serial pushes. See
the active-active protocol for the
state model, lease handling, explicit merge acceptance, privacy contract, and
local cleanup safeguards.
Every managed source ref has one CAS authority at
refs/heads/syncwheel/claim/heads/.... Each coordinated publication advances
that claim in the same atomic push as the source and state refs; an unchanged
claim is not accepted as lease evidence. Existing manifests normalize
coordination.claims to advisory. In that mode Syncwheel still creates claims
and reports gaps. Prepare an explicit switch to required with:
syncwheel coordination claims backfill
syncwheel coordination claims backfill --apply --reason "claim migration"Backfill uses create-only leases and never overwrites a foreign claim.
required refuses published state that lists an owned source without a claim.
Syncwheel covers concurrent Syncwheel commands, process death, ordinary Git on
unowned refs, and arbitrary readers. It fails closed on a detectable CAS,
ordering, intent, or recovery violation, and it never leaves state that a retry
of the recorded operation, or the next coordinated command, cannot resolve;
forced/raw mutation of Syncwheel-owned refs and hostile remotes remain outside
that guarantee.
Every mutating coordinated publisher records a durable operation token before the atomic push. If process death occurs after remote success, the retry accepts only state and claims carrying that token and completes without republishing, including when later publications have moved the shared state on. Draft create uses the same token in its create intent and remote claim, and cleans up its token-derived temporary worktree registration on retry.
One publication cycle runs at a time in a clone. Every coordinated command takes
<git-common-dir>/syncwheel/coordination-publication.lock around its whole
intent, push, local remainder and terminal event, and a second command refuses
with the live owner's pid rather than deciding anything about its intent; a
plain retry after it finishes succeeds. Process death releases the lock, so a
dead owner's intent is recovered by the next command. Dry runs and handoff
take no lock and are never refused.
A publication intent is always terminal, and a token has exactly one terminal
record; a second terminal is refused when it is written, never when the ledger
is read. Landing is proved by a state commit inside the intent's own window that
declares this operation's token, scope, changed refs, projection status and
manifest digest, together with a claim carrying that token for every touched
source ref; never by current ref tips, so another clone legitimately advancing
the same ref cannot turn a landed operation into an abandoned one, and a token
reused for another operation cannot prove this one. An intent with no recorded
expected state tip is never proved landed by the chain. Recovery, and only
recovery, accepts a second form after that one fails: every changed ref, and no
other, carrying a claim that declares this operation's token, scope and whole
ref set. That form has no window and no manifest digest, so it still holds when
a state ref is rewritten backwards, and a claim carrying the token under another
scope or another ref set proves a different operation, not this one. The digest
in both forms ignores integration.derived_provenance, which the two sides
resolve from different sources by design. An intent absent from that evidence
never reached the remote and is recorded as
coordination_publish_abandoned by the next publication, reconcile, or
resume, with reason not_landed when nothing else published meanwhile and
superseded when the reviewed state tip was overtaken; the local rename of an
abandoned promotion is undone only when the remote carries neither the promoted
ref nor a claim bearing its token. A promotion whose push landed before its
manifest save owes only that save: rerunning stack promote, stack rebuild
or stack add completes it from the published
state and rebuilds the promoted branch, so an intervening sync cannot strand
it, and a draft branch that came back with commits of its own is anchored under
refs/syncwheel/recovery/drafts/ before it is dropped. A clone that lost a
promotion race can also rerun stack promote: when the published stack,
managed ref, and promotion tombstone exactly match its draft, Syncwheel adopts
that published branch locally without republishing coordination state. A clone
whose publication was refused by the remote, or died before its push, keeps
publishing after a plain retry. A coordination remote that is unreachable, or
that refuses the atomic push without changing anything, fails closed and names
the retry command for stack push, int push, stack promote, stack create --draft, publish, reconcile --apply --push, and coordination claims backfill.
When a managed branch is correct but coordination state recorded the wrong tip, generate a digest-bound repair plan. The default backend remains non-mutating:
syncwheel coordination repair --ref refs/heads/main-integration > repair-plan.json
syncwheel coordination repair --apply --plan-file repair-plan.jsonApply rechecks the exact plan, ownership, pending merges, and every guarded ref.
Ordinary Git drops an unchanged no-op refspec, so there is no Git push fallback.
GitHub branch locks are not sufficient: administrators can bypass or change
them concurrently, so github-lock stops as unsupported before any state
update.
For the narrower case where the recorded and observed commits have exactly the
same tree, use --freeze-backend tree-equivalent-state-cas for both plan and
apply. This backend fetches and proves both commit trees, rechecks the state tip
and every managed ref, then pushes only an append-only state child under an
exact state-ref lease. It never updates the managed branch. Any different tree,
ownership uncertainty, ref drift, lease loss, or post-CAS drift stops
fail-closed; an accepted state child remains durable evidence even when the
post-verification reports failure.
When an actively managed ref has instead advanced through an exact, reviewed
fast-forward, use --freeze-backend fast-forward-state-cas. The plan binds the
recorded and observed tips and trees plus the complete bounded commit interval.
Apply repeats the ancestry and drift checks, then appends only state evidence
under the same exact state-ref lease. It never updates the managed branch and
refuses non-descendants, intervals above 1024 commits, plan drift, ownership
uncertainty, or concurrent ref changes.
When coordination state still owns a ref that was deleted remotely, use
--freeze-backend missing-ref-create-cas. The reviewed plan requires the ref
to remain actively declared and absent and the recorded commit object to exist
locally. Apply records a durable intent, then atomically creates that exact ref,
publishes a successor ownership claim, and appends a child state under exact
leases. A retry can complete an interrupted successful publication from its
operation token. Inactive or tombstoned refs are rejected; if any guarded ref
or claim appears or changes, nothing is overwritten.
A coordination state records the digest of .syncwheel/manifest.json on its
integration tip. States published before 0.42.2 recorded the digest of the
normalized public snapshot of that same manifest instead, so the guard accepts
either form and reports which one matched; anything else still fails closed.
The first publish, push, or compose over a legacy state rewrites the state with
the control-manifest digest and records a coordination_state_digest_migrated
ledger event. To migrate without publishing anything else, plan and apply with
--freeze-backend state-digest-migration: the plan reports
digest-migration-required instead of noop, binds both digests, and apply
appends a state child that changes only the recorded digest under the same
exact state-ref lease.
When the remote state and a stale local manifest independently added stacks,
compose the proposals explicitly instead of weakening stack push:
syncwheel coordination compose \
--stack new-stack \
--known-base-state <state-sha> \
--known-base-manifest-digest <integration-control-manifest-digest> > compose-plan.json
syncwheel coordination compose --apply --plan-file compose-plan.jsonCompose publishes only the requested local stack, beside additive remote stacks from the exact known base. Other unpublished local stacks stay in the local manifest and out of the published snapshot. Existing records, shared defaults, integration strategy, and membership order must be unchanged. A stack that is already published may also be named, to fast-forward its branch to new commits; nothing else about it can change. Apply rederives the complete plan, then atomically publishes only the requested stack ref and an append-only partial state child under exact leases. The integration ref is observed but never updated; unmapped integration commits remain unmapped diagnostics. If remote publication succeeds but local manifest adoption fails, replan produces an adopt-only operation and never repeats the push.
An explicit --manifest PATH overrides a personal selection inherited from the
environment or repository profile. Passing both --manifest and --personal
explicitly remains an error. The command does not change the stored profile.
Long options remain stable; short flags are available for daily workflows:
| Short | Long | Where |
|---|---|---|
-r |
--repo |
most repo commands |
-M |
--manifest |
most repo commands |
-p |
--personal |
most repo commands |
-j |
--json |
status, plan, check, ledger, reconcile |
-F |
--no-fetch |
check, reconcile, update/alignment flows |
-n |
--dry-run |
rebuild, push, self update/hooks, align-remote |
-a |
--apply |
reconcile and repo tracking set |
-P |
--push |
reconcile |
-R |
--remote |
reconcile, push, integration remote flows |
-W |
--worktree-root |
init, reconcile, stack absorb |
Examples:
syncwheel status -f -j
syncwheel repo tracking set git-tracked -a
syncwheel reconcile -a -P -W .syncwheel/wt
syncwheel stack rebuild feature-a -nThe safest default is:
- keep the primary working checkout on the shared integration branch
- rebuild and publish every PR branch from there, without checking it out
- optionally keep a separate administrative checkout for manifest-only work
- begin routine implementation, dependency installation, builds, and tests on integration
- create a desk only to resolve a conflict or validate a non-empty materialized stack when integration cannot safely run it
- an integration branch that is already checked out gets a detached desk, so the primary never moves during review
stack rebuild and int rebuild leave no worktree behind by default. Their
auto replay mode uses Git plumbing where Git supports it (2.38 or newer) and a
self-removing temporary worktree below that, the current checkout when it is
already on the target branch, and an existing worktree when the branch has one.
Pin a mode with --replay-mode, with syncwheel replay-mode <mode> for a
repo-local default, or with defaults.replay_mode in the manifest.
When another agent has explicitly locked or owns the primary checkout, continue authoring only by asking for a governed lane. This is an explicit fallback, not an automatic reaction to a lock:
syncwheel worktree open concise-change
syncwheel worktree open dependency-repair --fullopen creates one clone-local, registered worktree below the configured
syncwheel_worktree_root and prints its path. A light lane is for authoring and
committing only; Syncwheel does not provision dependencies there. --full is
the explicit, bounded choice when dependency installation, builds, tests, or
debugging are necessary. It is a lifecycle declaration, not a sandbox: a raw
shell can still bypass it, so agents must keep that boundary in their procedure.
Each clone warns when four active lanes are already open by default, while still
allowing another lane. A repository can change the warning threshold with
"governed_worktree_capacity": {"limit": 4} or explicitly enforce a hard cap with
"governed_worktree_capacity": {"limit": 4, "enforcement": "error"}.
enforcement accepts warn (the default) or error. The local registry records the owner,
lease, base, branch, target stack, mode, and any recovery ref in Git's common
directory, never in the shared manifest. Use --into <existing-stack> when the
destination is already known. Otherwise, after committing, use the existing
stack create, stack add, or stack capture-integration workflow from a
different clean checkout. Capturing commits from another owner's lane with a live
lease records stack ownership and reports captured, kept: owner <owner> live.
The lane stays active with its lease, checkout, index and refs unchanged; an
unproven foreign lease expiry is also retained. Coordinate explicit release with
its owner instead of treating capture as permission to remove their checkout.
For an eligible lane, once a stack owns every lane commit, Syncwheel anchors
the lane tip under refs/syncwheel/recovery/lanes/... and pushes the same tip
to refs/syncwheel/archive/lanes/... on the publication remote (or the
canonical remote when the publication one is not configured) before reaping
the clean worktree and local lane branch. The archive ref is outside
refs/heads, so forges do not list it as a branch, but anyone who can fetch the
repository can fetch it. If that push fails, or neither remote is
configured, the lane is kept with archive_push_failed and other commands
never stop on it; retry the same worktree release or gc --apply --lane.
Only a repository with no remote at all keeps just the local recovery ref. A dirty, unavailable, or current-directory lane
is retained and reported; it is never removed automatically. An expired lease
or a dead owner PID never removes a lane either: other mutating commands only
finish a capture or release that was already started, and report expired lanes.
A lane that someone holds with their own git worktree lock is skipped by that
finishing step with a warning, so it never stops unrelated commands; stack add
for its own stack, sync, publish, stack land and unscoped reconcile/resume
still refuse until it is released.
Apart from that and a captured lane whose cleanup fails, those whole-repository
commands stop on a lane that needs recovery only when it targets a stack still
declared in the manifest or its folder is checked out on a branch other than its
lane branch; other lanes, with no target or a closed stack, are reported as warnings.
Remove one with worktree release <lane>, or with gc --apply, which --lane <lane> (repeatable) limits to the named lanes; a missing lane whose lease
expired, or whose local owner PID is known to be dead, is eligible for gc
even when an old registry path is outside the current configured root. If Git
reports that the branch's worktree moved,
Syncwheel resolves and checks the current path before deciding whether the lane
is eligible, and retains moved dirty or externally locked worktrees.
The clone-local registry mutex records its PID, process start time, and a unique
token. A successor first obtains the old inode's non-blocking flock, then
atomically renames and logs it when the metadata proves owner death, PID reuse,
or an unreaped zombie. An empty or truncated lock is recovered only after a
brief initialization grace, so a plain retry can resume even when SIGKILL
lands between exclusive creation and metadata fsync. The creator verifies that
its inode still owns the lock path before entering the critical section, so a
stolen uninitialized lock never puts two processes inside it. That recovery is
reported as an uninitialized lock rather than a dead owner, because its creator
may be alive and merely descheduled, and the renamed inode is pruned by the next
cleanup once nobody holds it; the durable recovery log keeps the evidence. While
holding that mutex, cleanup takes a Git worktree lock with a deterministic
Syncwheel token before classifying the lane or changing a ref. A lock failure is
reported as a lane in use and stops the operation.
Under both locks, Syncwheel verifies the exact Git admin directory and its
gitdir, fsyncs a ledger governed_worktree_cleanup_intent, and saves the
pending registry state through a temp-file and parent-directory fsync guarded by
the observed pre-image digest. Stack create, add, and capture keep that intent
and its terminal event in the ledger selected by the effective shared,
personal, or external manifest. Only then may cleanup create the recovery ref
and commit one expected-old ref transaction that verifies the recovery ref
while deleting the lane branch. A restart rebuilds missing or rolled-back
registry state from the durable intent. A final tracked/untracked probe precedes
removal of the exact verified registration; cleanup never uses a global git worktree prune.
A reappearing path, changed registration, or moved recovery ref fails closed
with a retryable record. If a clean lane branch advanced after its first anchor,
the recorded gc --apply remedy anchors the new tip and completes while
retaining the earlier recovery ref. The locks cover concurrent Syncwheel cleanup
and ordinary non-forced Git worktree operations. Raw mutation of
Syncwheel-owned refs, double-force worktree operations, and direct non-owner
writes into a lane during cleanup are outside the supported concurrency model
and fail closed when their effects are detectable.
syncwheel worktree list (alias ls) shows every governed lane with its
state, health, target stack, branch, path and remedy; --problems keeps only the
lanes that need attention and --json adds a count per health code. It is
read-only. When more than three lanes need attention, other commands print one
summary line with those counts instead of one warning per lane.
Persistent stack replay desks created by Syncwheel also appear in worktree list; JSON output lists them under desks. Use stack release-desk STACK
to preview their recovery and removal before archiving a stack. The apply
requires the reviewed plan digest and confirmation that writers have stopped.
It retains the tip, index and working changes in local recovery refs before
removing the checkout. See desk release
for the command sequence and the explicit path selection for older desks.
status without --fetch, check --no-fetch, and worktree list preserve
control metadata, including authorization records, persistent caches and
startup state. They do not start update maintenance or clean up stale authorization records. Delivery
validation can still calculate projections using temporary Git objects and
checkouts; explicit fetch remains a separate, requested operation.
To retire a known dead or abandoned lane deliberately, preview the operation first and provide a durable reason:
syncwheel worktree release abandoned-lane --reason "superseded by pr/example"
syncwheel worktree release abandoned-lane --reason "superseded by pr/example" --applyrelease is dry-run by default. With --apply, it creates a recovery ref for
an existing lane-branch tip, pushes it to the remote archive ref, removes the
registry record, and appends a ledger event that names both refs. An explicitly abandoned record whose path is already missing can still
be released; any remaining Git worktree registration is removed before the
registry record. It refuses an existing dirty lane and names the recovery
remedy instead of removing it. Pending cleanup, including a branch that advanced
before its expected-old transaction, and ledger writes are retryable and
idempotent. An explicit release may supersede the automatic branch_advanced
intent, retain its earlier recovery ref, anchor the new tip, and close with the
operator's release reason; a release-originated retry retains its original
reason. A release also completes any other pending reap state, including one
left by SIGKILL, terminalizing it under the intent already fsynced for it. If
another Syncwheel command already terminalized the lane, or the first release
completed but its response was lost, the release reports that terminal ledger
event instead of an unknown lane. Whenever the recorded terminal is not this
operator's own release reason, --apply records that reason as a
governed_worktree_release_noted ledger event, once per terminal; the dry run
records nothing. gc reselects eligible lanes while holding the registry lock,
avoids stale lane-id reuse, and also works when active-active coordination is
disabled.
Automatic lane reaping runs only before an explicitly mutating lifecycle
operation. Status, check, handoff, gc without --apply, reconcile or
resume without --apply, and every other preview leave the registry,
branches, recovery refs, and ledger unchanged. stack git and int git join
that mutation allowlist only when --auto-worktree or --worktree explicitly
authorizes worktree creation; passthrough Git commands in an existing worktree
do not implicitly trigger lane reaping.
status, check, handoff, and gc include structured governed-worktree
diagnostics in JSON. Repo-aware terminal commands show actionable yellow
warnings for unfinished lanes when stderr is a TTY; NO_COLOR removes ANSI
color and JSON output remains free of ANSI sequences.
When an occupied primary checkout stops a mutating command, Syncwheel names
manifest-derived recovery commands in the error. For uncommitted tracked changes,
use syncwheel stack absorb <stack> <paths> -N -m "message" after identifying
their owning stack. Capture already committed, unowned primary work with syncwheel stack capture-integration <stack> HEAD, or leave
another agent's primary checkout unchanged and use
syncwheel worktree open <lane> --into <stack>. Capacity and expired-lane
diagnostics name the corresponding syncwheel stack add <stack> <base>..<lane>
queue command.
A commit made on the integration branch has to belong to a stack to reach the base branch. Until it
does, validate reports it as owned by nobody and the next integration rebuild drops it.
A draft stack closes that gap. It owns its commits like any other stack, but is forbidden from becoming a pull request until you promote it:
syncwheel stack create --draft caching-experiment
syncwheel stack capture-integration caching-experiment HEAD
syncwheel stack promote caching-experiment --branch pr/cachingstack capture-integration validates both the proposed stack and the complete
integration composition before persisting ownership. A conflict in another
stack must not leave a partial capture. Pending control recovery requires the
explicit command printed for the selected manifest; capture does not repair it
implicitly. Preserve the observed inputs and rerun the command if they change
while the capture is being validated.
Capture updates the stack ref, selected manifest and local ledger. It does not
stage or commit the manifest, even when tracking is git-tracked: the primary
HEAD and index stay unchanged. Publishing tracked control metadata remains a
separate delivery step.
A draft refuses stack push to the target remote and names its state as the reason. Under
active-active coordination its source ref does publish to the coordination remote, so another clone
can rebuild the draft from the manifest alone. Draft creation uses a create-only ref CAS and rechecks
cross-domain ownership at publication, so a concurrently created local ref or coordination claim is
preserved and reported instead of replaced. A retry adopts an equivalent completed remote create
before probing whether a new atomic push is possible. stack demote reverses the promotion, and
refuses when the stack already records an open pull request.
If commits were added after draft creation, rebuild the draft before promoting it.
Promotion first publishes the updated commit selection on the draft ref, then
publishes the promotion with the existing ownership and lease checks. An interrupted
refresh is safe to retry. Other stack-field changes require explicit publication.
From a governed authoring lane, stack add uses the primary control manifest by
default and resolves revision specs such as HEAD in the authoring lane; explicit
manifest and personal selectors retain their existing behavior.
Closing a never-published draft is remote-first under active coordination. It
records stack_close_intent, atomically publishes a tombstone claim plus state,
saves the manifest, and only then records stack_closed. A retry after a crash
between push and save recognizes its operation token in the tombstone and
completes idempotently; an unreachable remote fails closed without changing the
manifest, including during recovery. If a later create has advanced the claim,
the old close is terminalized as close_superseded and cannot close the new
generation. A close whose tombstone already landed completes from its intent
even when unrelated publications have advanced the state, instead of publishing
a second tombstone.
A coordinated close, of a draft or of a published stack, publishes the
published coordination state minus the closed stack. Unpublished local changes
to other stacks stay local and no longer block the close, and a stack that
another clone published but this manifest lacks stays published. The saved
local manifest is the local manifest minus the closed stack. A retried published
close looks for its token in the state history and in the closed ref's claim
history before any delivery or ancestry proof. A close that already landed
completes locally without publishing again, whatever changed locally or on the
delivery branch since, and refuses only a different --reason. When this clone declared
the same stack id again after that close, or its published entry matches the
local one, the old intent is recorded as recovered and the command closes the
stack as a new operation. A close that never landed is
abandoned and the retry writes a new intent against the current state, unless
the stack's published entry changed in between: then the retry stops with
close_superseded and the next run starts fresh. Choose the close proof from
the delivery method:
syncwheel stack close feature-a --reason merged # normal merge or fast-forward
syncwheel stack close feature-a --reason absorbed # squash or rebaseabsorbed first fetches and records the observed delivery SHA, then compares
the fully composed stack result with that delivery tip for every touched path.
Squash-equivalent delivery is accepted; a historical patch later reverted at
the tip is not. A verified absorbed close does not need --force.
When plan finds integration commits belonging to no stack, it now names capture-integration into a
new draft as the remedy.
When the owning stack already exists and its source branch must remain unchanged, classify the commit declaratively instead. Preview is the default; apply requires the exact digest printed by the preview:
plan=$(syncwheel stack classify-integration caching-experiment HEAD)
digest=$(printf '%s' "$plan" | jq -r .planDigest)
syncwheel stack classify-integration caching-experiment HEAD --apply --plan-digest "$digest"This writes only the manifest and ledger. The commit is recorded in
integration_only_commits and remains part of future integration rebuilds,
including merge-stacks, without being projected onto the stack branch. These
commits replay after the combined stack projection so they retain the context in
which integration-first work was created.
stack land is the bounded alternative to a PR when a maintainer explicitly
asks to land an already-validated stack. It does not create a lane type, open a
PR, close a stack, deploy a channel, rewrite history, or mutate
main-integration. A preview rechecks the exact declared source projection,
combined integration projection, clean worktrees, dependency ancestry, remote
delivery tip, and (when enabled) active-active coordination. Its planDigest
binds a second --apply invocation; apply re-runs the same checks and pushes
only through an exact lease.
plan="$(syncwheel stack land caching-experiment --allow-direct --operation-id cache-land-01)"
digest="$(printf '%s' "$plan" | jq -r .planDigest)"
syncwheel stack land caching-experiment --allow-direct --operation-id cache-land-01 \
--plan-digest "$digest" --applyRepositories can opt in with a root landing policy. With no policy,
--allow-direct is required for the specific request. mode: "direct" permits
the normal path; mode: "disabled" retains the explicit bypass requirement.
The optional checks field is a small all/any tree of local commands,
receipt attestations, and PR-check route markers. A failed PR marker or a
protected remote ref stops and suggests stack promote; Syncwheel never opens
the PR itself. Every check override needs a reason and is retained in the
digest-bound plan and ledger receipt.
A channel pins an exact base revision plus a selected, ordered composition of
stacks pinned to exact branch revisions, commit lists, base provenance, and
depends_on closure/order. It is intentionally separate from:
- a stack, which owns one change stream;
- the integration branch, which represents the full current integration projection;
- a deployment, which is external environment state managed by CI/CD or another system.
Channels may be shared (for example a stable test input) or ephemeral (for
example a short-lived feature input with explicit expiry metadata). They do not
follow base or stack tips automatically: channel refresh updates pins
deliberately.
Explicit depends_on metadata is version 3-only. The reviewed v2-to-v3 channel
migration derives direct dependencies from existing stack base chains.
Every mutation previews a channelPlan; --apply requires its exact
planDigest. Durable operations record started/prepared/receipt evidence, and
publishing uses an exact lease. A channel-local resolution snapshot can capture
a resolved composition without rewriting its stacks; composition edits
invalidate it. Expiry never deletes a branch automatically; use channel close
for explicit cleanup.
Shared channels refuse publication when they contain draft stacks. Ephemeral channels may include drafts for temporary testing. Under active-active coordination, every channel uses the coordination remote so its branch and coordination state publish atomically.
Publishing channel/test proves only that a specific Git composition is
available on that branch. It does not prove that an environment has deployed
or is healthy. See deployment channels for the
complete CLI, failure, and CI/CD boundary.
syncwheel has six pieces:
- base branch (
upstream/mainor similar) - PR stacks mapped to
pr/*branches - manifest (
.syncwheel/manifest.json) as source of truth - integration branch (
main-integrationby default) for combined testing - optional deployment channels for pinned, selected compositions
- ledger (
.syncwheel/ledger/for the shared manifest, or a sibling<manifest-name>-ledger/directory for personal and external manifests) as append-only operational history plus a replay checkpoint for cross-machine recovery
flowchart LR
U[upstream/main]
I[main-integration]
P1[pr/feature-a]
P2[pr/feature-b]
P3[pr/hotfix-c]
M[.syncwheel/manifest.json]
U --> P1
U --> P2
U --> P3
M --> P1
M --> P2
M --> P3
M -. optional .-> I
P1 -. sync .-> I
P2 -. sync .-> I
P3 -. sync .-> I
I -. sync .-> P1
I -. sync .-> P2
I -. sync .-> P3
Practical meaning:
- PR branches are rebuilt from declared commit ownership
- integration (if used) is rebuilt from declared stack order
- one manifest keeps both sides aligned
- branch rebuilds create a backup branch first when the target branch already exists
- A PR stack is one logical change stream mapped to one
pr/*branch with an explicit commit list. stack sync,stack set, andstack addupdate commit ownership without hand-editing SHA lists.stack classify-integrationrecords integration-only ownership through a digest-bound manifest plan without rebuilding a stack or integration ref.stack absorbmoves dirty or staged integration-branch changes into a stack branch, updates the manifest, and removes the absorbed patch from the integration checkout.stack rebuildrebuilds one PR branch from the manifest.int rebuildrebuilds integration from ordered stacks.channel planpreviews channel materialization or publication; every channel mutation requires its exact digest, andchannel publishuses an exact lease.channel operation list/show/reconcileexposes durable operation intent and observes uncertain outcomes without retrying a mutation.stack pushandint pushare targeted publication commands. On active version 2 or 3 manifests they publish a partial atomic state snapshot; legacy manifests retain the direct Git push wrapper and its optional arguments.stack pushpublishes only the selected stack branch plus its coordination claim/state; local control-manifest persistence never authorizes publishing the integration branch. Bootstrap or publish integration explicitly withint push. With coordination active,stack pushandint pushfrom a secondary worktree refuse before any write unless its control manifest matches the primary checkout's.reconcileis the preferred multi-device maintenance entrypoint: it compares manifest ownership, stack branches, integration, and remote tips; reports a dry-run plan by default; and can rebuild, update manifest SHAs, and push when explicitly run with--applyand--push.- Stack-scoped
reconcileandresumereport unrelated dirty governed lanes without reaping them. A live lane targeting a selected stack still blocks that stack's mutation. - In multi-device workflows,
reconcileconverges toward a remote branch that already matches the manifest projection instead of rebuilding the same logical state into new SHAs on every device. validateandplandetect drift before branch mutation.- validation also reports non-merge commits on integration that are not declared in any stack, so integration-only work cannot hide silently.
- update detection also works for normal branch checkouts and detached submodule-style installs.
integration.strategycontrols how integration is rebuilt:cherry-pickreplays every declared commit into one linear history.merge-stacksmerges each declared stack branch in manifest order with--no-ff, preserving an integration history made of merge commits.
syncwheel is for teams or maintainers who have at least one of these conditions:
- active upstream + fork workflow, especially in open source
- multiple PR branches that must stay clean while development continues
- long-lived PRs that need regular rebuilds on top of a moving base branch
- an
integration/*branch used as day-to-day runnable state - multi-device or AI-agent workflows where no single checkout should be considered authoritative
- need for repeatable branch recovery that does not depend on memory
syncwheel is usually overkill when:
- you ship directly from one branch with short-lived PRs only
- your repo has no integration branch and no stacked branch maintenance
- your process does not need deterministic rebuilds from a declared manifest
-
Guide-first (manual execution)
Use docs/manual-git-flow.md as an operating playbook and run the underlying Git steps manually. This is possible, but cognitively heavier and easier to get wrong in complex branch graphs. -
Script-assisted (human-operated)
Use the CLI for discovery, validation, manifest updates, branch rebuilds, Git wrappers, and push wrappers while a human decides what to run and when. This is a strong middle ground once the team knows the model well. -
AI-operated (recommended)
Let an AI agent run the syncwheel flow through prompts, with a human supervising intent and approval boundaries. In practice this gives the best speed/consistency balance for ongoing maintenance.
For repositories that explicitly use ai-managed source delivery, the
optional digest-bound GitHub PR merge path is documented in
docs/github-pr-merge.md. Its private policy stays
clone-local and its admin bypass is limited to required reviews. Its allowed
bases are exact names or PREFIX/* patterns such as save/* for release
branches. CI is required
by default; repositories without CI can explicitly select clone-local
checks: "none", which remains visible as a merge-plan warning. Integration
validation is required by default too; a clone whose integration branch is often
behind can select integration: "advisory", which turns missing integration
commits into a merge-plan warning.
CLI install
uv tool install "git+https://github.com/NestDevLab/syncwheel"
syncwheel self statusAI agent handoff
Give an agent install.md when you want it to install Syncwheel, verify the CLI, inspect
a repository, and install the companion skill through Agentwheel.
curl -fsSL https://raw.githubusercontent.com/NestDevLab/syncwheel/main/install.mdCompanion skill
When Agentwheel is available, install the Syncwheel skill into the runtime you are using:
agentwheel doctor --adapter codex --local --skill syncwheel --source github:NestDevLab/syncwheel
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --skill syncwheelRequirements:
- Python 3.11+
- Git
- uv 0.10+ for PATH-based installs
Recommended production install:
uv tool install "git+https://github.com/NestDevLab/syncwheel"Development editable install from a local checkout:
uv tool install --editable .Installer script:
scripts/install.sh
scripts/install.sh --editable /path/to/syncwheelIf uv is not installed, scripts/install.sh exits with instructions by
default. To explicitly let the installer bootstrap uv with the official
astral.sh installer, pass --with-uv.
Legacy checkout execution remains supported for pinned submodules, vendored checkouts, and existing scripts:
python3 scripts/syncwheel.py --helpSyncwheel now includes a built-in install/update channel so humans and AI agents can notice new releases instead of silently drifting.
- default mode:
notify - automatic notice is emitted on normal syncwheel usage when the local install is behind the configured update source
- git-checkout installs update with the existing
git fetchplus fast-forward merge flow - uv tool installs update with
uv tool upgrade syncwheel - manual inspection:
syncwheel self status
syncwheel self check-update --fetchWhen Agentwheel is on PATH, self status also checks whether the local Codex
runtime has the Syncwheel agent skill installed for the current repo. Install it
with:
agentwheel install github:NestDevLab/syncwheel --adapter codex --local --target-root /path/to/repo --skill syncwheelIf the syncwheel executable is not installed yet, run the same status checks
through the checkout script:
python3 /path/to/syncwheel/scripts/syncwheel.py self status
python3 /path/to/syncwheel/scripts/syncwheel.py self check-update --fetch- manual update:
syncwheel self update- update policy:
python3 scripts/syncwheel.py self mode notify
python3 scripts/syncwheel.py self mode auto
python3 scripts/syncwheel.py self mode offauto tries a safe fast-forward self-update when a newer upstream version is
detected for git-checkout installs and runs the uv tool updater for uv installs.
If a git checkout is dirty or detached, syncwheel falls back to a visible notice
instead of mutating it unsafely.
For uv installs, self check-update reads the upstream VERSION file directly
instead of requiring a local git checkout. Advanced wrappers can override the
version source with SYNCWHEEL_REMOTE_VERSION_URL and the installer/update
source label with SYNCWHEEL_UV_TOOL_SOURCE.
-
uv production tool (recommended for normal hosts)
- Run
uv tool install "git+https://github.com/NestDevLab/syncwheel". - The
syncwheelexecutable is placed on PATH when uv's tool bin directory is configured in the shell. syncwheel self updateuses uv to upgrade the installed tool.
- Run
-
uv editable development tool (recommended for syncwheel development)
- Clone
syncwheelonce in a stable location. - Run
uv tool install --editable /path/to/syncwheel. - The
syncwheelexecutable reflects local source edits immediately. syncwheel self updatetreats the checkout as a git install and uses the existing fast-forward flow against the clone's upstream.
- Clone
-
Git submodule
- Add
syncwheelas a submodule inside each target repo. - Good when each project must pin an explicit syncwheel version.
- Invoke it with
python3 path/to/syncwheel/scripts/syncwheel.py .... - Self-update status works for detached submodule-style checkouts; updating remains controlled by the parent repository's submodule policy.
- Add
-
Vendored checkout or module bundle
- Copy the complete
scripts/syncwheel*.pysibling set andVERSIONinto one directory in the project. This includes the CLI, revision provider, GitHub adapter and domain modules declared inpyproject.toml. - Invoke
python3 path/to/bundle/syncwheel.py .... - Copying only
syncwheel.pyis no longer sufficient. Keep all sibling modules from the same revision and replace the bundle together for manual updates. self statusreportsinstall_kind: scriptwhen no git checkout or uv tool environment is detected. Vendored updates remain manual.
- Copy the complete
You can register repo aliases and keep commands short.
python3 scripts/syncwheel.py repo add project ~/code/sample-project
python3 scripts/syncwheel.py repo ls
python3 scripts/syncwheel.py self status
python3 scripts/syncwheel.py self check-update --fetch
python3 scripts/syncwheel.py self update
python3 scripts/syncwheel.py self mode notify
python3 scripts/syncwheel.py status -r project --fetch
python3 scripts/syncwheel.py repo rm project-r/--repo accepts both:
- a filesystem path
- a registered alias
Alias entries can also carry a default manifest path (useful for private/local manifests on public repos):
python3 scripts/syncwheel.py repo add service ~/code/sample-service \
--manifest ~/.config/syncwheel/manifests/sample-service.json
python3 scripts/syncwheel.py repo set-manifest service ~/.config/syncwheel/manifests/sample-service.json
python3 scripts/syncwheel.py repo set-manifest service --clearYou can also set SYNCWHEEL_REPO when wrapping syncwheel from another project:
SYNCWHEEL_REPO=/path/to/repo python3 scripts/syncwheel.py checkCreate the shared manifest with init:
python3 scripts/syncwheel.py initCreate a personal local manifest without copying or hand-writing JSON:
python3 scripts/syncwheel.py init --personal aliceThis writes .syncwheel/manifests/alice.local.json and defaults its integration
branch to integration/alice/main. Its operational history is isolated in
.syncwheel/manifests/alice.local-ledger/. Use -p alice on later commands
when you want to target that personal manifest:
python3 scripts/syncwheel.py check -p alice
python3 scripts/syncwheel.py s new -p alice feature-a --branch pr/alice/feature-a
python3 scripts/syncwheel.py s set -p alice feature-a origin/main..HEADLong names are still available: stack create --personal alice is equivalent,
and spoke is a readable alias for stack. New manifests include every declared
stack in integration by default; use ordinary Git worktrees for work that should
not enter the Syncwheel lifecycle.
To make a personal manifest the default for the current clone:
python3 scripts/syncwheel.py use alice
python3 scripts/syncwheel.py check
python3 scripts/syncwheel.py use --shareduse alice writes .syncwheel/profile.local.json, which should be ignored by
the host repository because it is local operator state. syncwheel replay-mode <mode> stores the repo-local default replay execution mode in the same file.
Each stack can include optional meta fields so humans and AI can understand intent better.
Example:
{
"id": "endpoint-resolution-policy",
"branch": "pr/endpoint-resolution-policy",
"commits": ["abc1234"],
"meta": {
"purpose": "Endpoint policy and routing",
"status": "active",
"priority": "p1",
"dependencies": [],
"integrationPolicy": "required",
"notes": "Keep in integration for runtime validation"
}
}python3 scripts/syncwheel.py init
python3 scripts/syncwheel.py checkFor a custom integration branch:
python3 scripts/syncwheel.py init --integration-branch integration/team-stackUse --stdout only when you need to pipe the generated manifest instead of
writing it to .syncwheel/manifest.json.
python3 scripts/syncwheel.py stack create feature-a --branch pr/feature-a
python3 scripts/syncwheel.py stack sync feature-a
python3 scripts/syncwheel.py stack set feature-a origin/main..HEAD
python3 scripts/syncwheel.py stack add feature-a HEADUse stack sync when the branch already represents the intended PR stack. Use
stack set or stack add when you want to declare an explicit revision range
or append a new commit.
stack sync updates the selected manifest and its ledger. Unrelated unstaged
product changes in the primary are preserved, along with its index and ignore
files. Pending promotion or control recovery must be completed through the
printed explicit remedy before retrying; syncing does not recover promotions or
clean up worktrees. Conflicts, staged changes and dirty shared control metadata
remain blocking.
After a parent PR lands, use stack set <id> --target-branch main to update
only the stack's delivery target. Source commits, base, branch refs and integration
mappings remain unchanged; GitHub PR retargeting is a separate operation. The
command validates the branch name, rejects source/integration targets and
--published combinations, and records previous/new targets in the ledger.
Commit specs may be supplied to update both fields in one operation.
Under active-active coordination, stack set <id> --published drops an
unpublished local change to a published stack: it resets the stack's commits to
its entry in the published coordination state, records the previous commits and
the actor in the ledger, and prints the exact stack set <id> <commits...>
command that restores them. It refuses for a stack that is not published and for
a local entry that differs in anything other than its commits. Published commits
missing locally are fetched once from the coordination remote; if they are still
missing, it refuses and names the owner.
When uncommitted changes already exist on the integration checkout, transfer them to their owning stack before continuing:
python3 scripts/syncwheel.py stack absorb feature-a path/to/file.ts -N -m "Add feature work"
python3 scripts/syncwheel.py stack absorb feature-a --staged -N -m "Add staged feature work"By default, stack absorb amends the stack branch tip, refreshes that stack's
manifest commits, and reverse-applies the absorbed patch from the integration
checkout. Pass --no-amend -m "message" when the absorbed change should become
a new stack commit. An empty stack requires this option: default amend is refused
so its base commit cannot be amended. If an empty recipe has a branch that has
already moved away from its base, absorb refuses: preserve that history for
explicit classification and use a fresh draft for the patch. capture-integration assigns existing
commits; it does not capture dirty working-tree bytes. Use --staged after git add -p when one file contains
changes for multiple PR stacks.
Example: two files belong to feature-a, one file belongs to feature-b, and
one mixed file has hunks for both stacks:
python3 scripts/syncwheel.py stack absorb feature-a a1.ts a2.ts
python3 scripts/syncwheel.py stack absorb feature-b b1.ts
git add -p shared.ts
python3 scripts/syncwheel.py stack absorb feature-a --staged
git add -p shared.ts
python3 scripts/syncwheel.py stack absorb feature-b --staged
python3 scripts/syncwheel.py syncUse reconcile as the normal maintenance entrypoint:
python3 scripts/syncwheel.py repo tracking status
python3 scripts/syncwheel.py reconcile
python3 scripts/syncwheel.py resume
python3 scripts/syncwheel.py sync
python3 scripts/syncwheel.py publishreconcile fetches by default, classifies stack and integration drift, and
prints a dry-run plan. sync runs the same lifecycle locally: it rebuilds only
branches that differ from the manifest projection unless --rebuild all is
passed, refreshes stack commit SHAs after rebuilds, and rebuilds integration
from the current manifest. publish does the same local work and then uses
Syncwheel push wrappers for managed branches. The report also prints the
current working tree status, including uncommitted files, before validation and
drift details so dirty checkouts are visible without running a separate
git status.
resume is a thin recovery layer on top of reconcile. It pre-classifies
unmapped integration commits when ownership is deterministic, then runs the
normal reconcile planner on the resulting manifest. Use either form:
python3 scripts/syncwheel.py reconcile --mode resume
python3 scripts/syncwheel.py resumeIn resume mode Syncwheel can:
- add an unmapped integration commit to an existing owning stack when exactly one owner is detected
- restore a previously known historical stack from the ledger when the branch still exists locally or remotely and ownership is unambiguous
- leave the commit in manual review when ownership is ambiguous
The shared manifest's ledger lives under .syncwheel/ledger/. Every other
manifest gets a sibling ledger derived from its filename, so parallel personal
or external manifests cannot overwrite one another's checkpoint. For example,
.syncwheel/manifests/alice.local.json uses
.syncwheel/manifests/alice.local-ledger/, while
docs/syncwheel/glow-portals-manifest.json uses
docs/syncwheel/glow-portals-ledger/.
Each ledger root contains:
events/000001.jsonl,000002.jsonl, ... contain append-only event segmentscheckpoints/latest.jsoncontains the replayed current state for fast reads
Use this to inspect the current replayed ledger state:
python3 scripts/syncwheel.py ledger show
python3 scripts/syncwheel.py ledger show --jsonWhen integration contains non-merge commits that are not declared in any stack,
check and reconcile print commit-level guidance: short SHA, subject, touched
files, local and remote branches containing the commit, likely stack owners, and
suggested next commands such as syncwheel stack add <stack> <sha> followed by
syncwheel reconcile. This keeps the common integration-first repair path
inside Syncwheel instead of requiring separate git log, git show, and
git branch --contains commands.
When the remote branch already matches the manifest projection, sync,
publish, and reconcile --apply align the local branch to the remote and do
not update the manifest or push new replacement commits. Pass
--no-align-local-to-remote when you intentionally want to preserve a different
local history for manual inspection:
python3 scripts/syncwheel.py sync --no-align-local-to-remoteLegacy publish and reconcile --push use --force-with-lease by default
because rebuilt managed branches commonly replace older remote history in
multi-device workflows. Active version 2 or 3 manifests instead use the coordinated
atomic publisher and reject manual force, lease, or remote overrides.
Use --json for automation, --stack <id> to limit stack work, --remote to
override the publication remote, and --in-place-integration only when the
current checkout is already on the clean integration branch and should be reset
as part of the reconcile.
reconcile is the preferred lifecycle command. The object/action commands are
still useful for targeted repair and inspection:
python3 scripts/syncwheel.py validate
python3 scripts/syncwheel.py plan --json
python3 scripts/syncwheel.py stack absorb feature-a path/to/file.ts
python3 scripts/syncwheel.py stack rebuild feature-a --worktree ../wt-pr-feature-a
python3 scripts/syncwheel.py stack push feature-a
python3 scripts/syncwheel.py stack git feature-a --worktree ../wt-pr-feature-a -- status
python3 scripts/syncwheel.py int rebuild --worktree ../wt-integration --reason "refresh integration projection"
python3 scripts/syncwheel.py int push
python3 scripts/syncwheel.py int git --auto-worktree -- status
python3 scripts/syncwheel.py int sync-status --jsonUse --dry-run on rebuild and push commands to print commands without applying
them. If the remote integration branch already matches the manifest projection
and the local checkout is stale, int align-remote can align a clean local
integration checkout to the remote with a backup branch first.
When two devices or workstreams use different manifests and integration branches, compare the manifests instead of merging their integration branches:
python3 scripts/syncwheel.py manifest compare --other-personal laptop --json
python3 scripts/syncwheel.py manifest compare --other-manifest ../other-manifest.jsonThe comparison reports shared stacks, stacks only present in one composition, and shared stacks whose branch/base/commit list diverges.
Inspect or explicitly manage the repository-local, composable hook bundle:
syncwheel hooks status
syncwheel hooks install
syncwheel hooks install --apply
syncwheel hooks remove
syncwheel hooks remove --disable --reason "external contribution clone"
syncwheel hooks remove --disable --reason "external contribution clone" --applyThe pre-push guard derives guarded refs from the manifest and published coordination state,
including integration, stack and draft sources, channels, coordination state, an
owned journal branch, and the delivery branches that only stack land may publish.
It blocks direct, aliased, multi-ref, delete, force, and HEAD:<managed> pushes,
then names the corresponding Syncwheel publisher. In a linked worktree, the
pre-push hook also protects the refs declared locally by the primary manifest,
without contacting the primary's publication remote. Existing hooks are chained
and restored on removal; core.hooksPath is honored.
The same bundle installs post-checkout, pre-commit, and reference-transaction guards
for the primary checkout (0.42.4+). post-checkout compares the worktree with the declared
branch and reports a visible failure if a checkout moved it elsewhere — Git has already
completed the switch, so restore a mismatched checkout losslessly rather than resetting
dirty work. pre-commit blocks both that mismatch and a manual commit while the primary is
correctly on the integration branch. reference-transaction blocks every unauthorized
update to the integration ref, including a fast-forward, rewind, creation, or deletion, that
did not go through Syncwheel. Syncwheel's own control and in-place rebuild commits pass
through a short-lived, single-use, per-process nonce; dedicated feature worktrees and
plumbing-materialized branches are unaffected. A refusal names syncwheel worktree open <lane> --into <stack> for new work or syncwheel stack capture-integration <stack> HEAD
for work already committed on the primary. Mutations that can change primary product
paths refuse to start while the primary has unrelated tracked changes.
Bounded metadata operations can preserve those changes in place: setting authority
on an untracked personal manifest, setting or clearing the private PR merge policy,
closing an empty non-coordinated draft with the default reason or --reason closed,
without forcing or deleting its branch, and
archiving a non-coordinated stack through its exact plan, and stack sync without
pending recovery. Existing index conflicts,
unrelated staged paths and a dirty shared control manifest still stop them. Archive
keeps the required recovery refs; close retains the source branch by default.
Authority updates do not force-stage the selected manifest. Saving a local profile or appending a ledger event does not normalize ignore files; configure tracking explicitly when exclusions need to change. Pending control recovery on a dirty primary remains a refusal with an explicit recovery remedy, never an incidental part of a metadata operation.
int git authorizes every ref move of its own Git process, so a cherry-pick range or rebase
lands completely. If such an operation pauses on the primary, finish it with
syncwheel int git -- <operation> --continue (or --abort, --skip, --quit); any other
mutation stays refused until the operation ends.
Because of that authorization, int git refuses arguments that would act outside the
checked-out integration branch: update-ref, symbolic-ref writes, Git aliases (configured
or passed with -c alias.*), -c overrides of hook, worktree or include settings, and
-C, --git-dir, --work-tree and the other options that point Git elsewhere, and
fetch --update-head-ok and its long abbreviations. Fetch runs without integration-ref
authorization. If a
command leaves the integration worktree on another branch, it exits non-zero and names
the branch to switch back to. Read-only commands, such as symbolic-ref HEAD,
worktree list and stash list, run without the dirty-primary refusal.
For git-tracked repositories the bundle is required by default. Status and
validation report an absent, stale or damaged bundle; normal commands do not
install it implicitly. A lane manifest that does not own the primary checkout is
checked against its own managed refs. Its different integration branch is not a
reason to retarget the shared primary guard. Repair that guard only through the
manifest that owns the primary, after reviewing the hook installation plan.
Explicit hooks status|install|remove commands remain observational or plan-first.
Existing non-Syncwheel hooks are chained and restored on removal. local-only
contribution clones remain opt-in. A persisted clone-local disable requires a
non-empty reason and stays visible in validation.
Syncwheel publishers use a short-lived, single-use authorization scoped to the remote and allowed destination refset.
These hooks are local safety rails, not a security boundary. --no-verify, deleting
the hooks, or operating from a clone before its first normal Syncwheel command can
bypass them.
See the managed repository guard design
for server-side hardening options.
Syncwheel includes a pre-commit hook that runs the version-bump guard against staged files. Enable the tracked hooks once per clone:
python3 scripts/syncwheel.py self install-hooksAfter that, the hook renders the two website version labels from VERSION and
stops once when docs/index.html needs to be reviewed and staged. Commits that
stage release-relevant changes under scripts/, tests/, or githooks/ must
also stage VERSION, CHANGELOG.md, and the README current-version line. CI
checks that the committed static site matches VERSION.
Run the same deterministic website render directly with:
python3 docs/sync_version.pyself status reports whether the hooks are active in the current Syncwheel
installation. See docs/manual-git-flow.md for the
raw Git equivalent of the Syncwheel lifecycle.
scripts/syncwheel.py: main CLIscripts/syncwheel_revision_provider.py: strict Agentwheel revision-provider protocolscripts/syncwheel-status.sh: small compatibility wrapperdocs/: human-readable workflow docs and guidesdocs/sync_version.py: renders the checked-in website version fromVERSIONexamples/manifest.example.json: starter manifesttests/: unit tests and fixture repositoriesVERSION: current release versionCHANGELOG.md: release notes
Syncwheel keeps a clone-local patch-ID cache in Git's common directory. Its key
covers only the Git config and GIT_* environment that can change a diff, so a
session with its own user.*, credential, remote or tracing settings reuses the
same cache instead of recomputing every commit. Within one command, Syncwheel
also remembers Git answers that cannot change while it runs (existence of full
commit ids, ancestry between fixed commits, parents, changed files, the common
directory); refs are always read fresh.
install.md: AI-agent handoff for installing Syncwheel and the companion skillAGENT.md: concise operating guide for AI agentsllms.txt: LLM-oriented map of the public docsdocs/workflow.md: concise workflow modeldocs/core-procedure.md: deterministic recovery proceduredocs/manual-git-flow.md: raw Git equivalent of the Syncwheel lifecycledocs/revision-provider.md: Agentwheel revisioning protocol and recovery contract, including blob-exact manifest-base/derived routing, NUL-safe Git paths, Git-common-dir and coordinated content-bound provenance, snapshot precedence over the clone-local cache, stale/narrowed projection repair, the single-clone limit of uncoordinatedderived_paths, and the accepted derived-route delivery costdocs/branch-model.md: branch role model and safety defaultsdocs/deterministic-model.md: manifest semantics and validation contractdocs/design/active-active-coordination.md: active-active publication and recovery protocoldocs/deployment-channels.md: pinned channel model, CLI, receipts, and CI/CD boundarydocs/ai-agents.md: short AI behavior contractdocs/agent-procedure.md: extended AI execution guidancedocs/workflow-longform.md: long-form practical workflow guidedocs/public-article.md: narrative article version for broader audiences
python3 scripts/syncwheel.py --help
python3 scripts/syncwheel.py --version
python3 scripts/syncwheel.py init --help
python3 scripts/syncwheel.py coordination --help
python3 scripts/syncwheel.py handoff --help
python3 scripts/syncwheel.py revision-provider --help
python3 scripts/syncwheel.py gc --help
python3 scripts/syncwheel.py worktree --help
python3 scripts/syncwheel.py check --help
python3 scripts/syncwheel.py status --help
python3 scripts/syncwheel.py validate --help
python3 scripts/syncwheel.py plan --help
python3 scripts/syncwheel.py reconcile --help
python3 scripts/syncwheel.py ledger show --help
python3 scripts/syncwheel.py resume --help
python3 scripts/syncwheel.py sync --help
python3 scripts/syncwheel.py publish --help
python3 scripts/syncwheel.py journal status --help
python3 scripts/syncwheel.py journal snapshot --help
python3 scripts/syncwheel.py journal publish --help
python3 scripts/syncwheel.py journal pull --help
python3 scripts/syncwheel.py journal schedule --help
python3 scripts/syncwheel.py channel --help
python3 scripts/syncwheel.py channel contract
python3 scripts/syncwheel.py channel operation --help
python3 scripts/syncwheel.py stack --help
python3 scripts/syncwheel.py stack close --help
python3 scripts/syncwheel.py int --help
python3 scripts/syncwheel.py stack rebuild --help
python3 scripts/syncwheel.py stack push --help
python3 scripts/syncwheel.py stack git --help
python3 scripts/syncwheel.py int rebuild --help
python3 scripts/syncwheel.py int push --help
python3 scripts/syncwheel.py int git --helpSet repository_mode to journal for a single-branch repository that records
an allowlisted working tree without PR stacks or integration. The manifest's
journal object declares branch, remote, include, exclude,
max_file_bytes, and an optional interval (default 30m).
syncwheel check --no-fetch # validate local journal state
syncwheel journal status
syncwheel journal snapshot # plan
syncwheel journal snapshot --apply # locked temporary-index commit
syncwheel journal snapshot --path notes.txt --path docs/status.md --apply
syncwheel journal publish --committed-only --apply # never snapshot unfinished edits
syncwheel journal publish # plan snapshot and exact-lease push
syncwheel journal publish --apply
syncwheel journal pull # fetch and plan a fast-forward to the remote tip
syncwheel journal pull --apply
syncwheel journal pull --apply --park-conflicts # save, fast-forward, three-way merge
syncwheel journal schedule install # plan a Linux systemd user timer
syncwheel journal schedule install --apply
syncwheel journal schedule install --committed-only --applyJournal check validates the configured branch, remote, and repository guards
using local state with --no-fetch. --strict fails on warnings or a dirty
worktree. It does not validate an integration projection or prove the remote
journal is current; use journal status for the remote tip.
journal publish prints excluded_count and pull.kept_local_count in both
plan and apply results. Its other result fields remain available. Use
journal status --json to inspect the full excluded path list; journal snapshot
and journal pull retain their full diagnostic lists.
Whole-tree journal snapshots require a clean real index. Exact --path snapshots
preserve unrelated staged entries and working files; each path is a literal,
normalized repository-relative file name. All snapshots refuse sensitive paths, oversized files,
and high-confidence secrets. Publication never merges, resets, rebases, or
force-updates a remote.
To migrate an already converged delivery repository, preview and then apply:
syncwheel repo mode set journal --branch main --remote origin --reason "Use linear operation history"
syncwheel repo mode set journal --branch main --remote origin --reason "Use linear operation history" --applyThe primary checkout must be clean and the existing target branch must have the
exact current tree. The command archives the original manifest and stack commits
locally, drops delivery/coordination declarations, switches branches, and retargets
the guards. It preserves unknown metadata and never deletes remote refs. Review
--include, --exclude, --interval, and --manifest-version in the plan before
applying. Commit the resulting manifest with an exact-path journal snapshot.
Journal repositories also support the revision provider for local operation commits; use committed-only publication to publish those commits without collecting another writer's unfinished files. Under a path-scoped HEAD lease, a prepared commit that an unrelated writer overtakes is rebuilt on the new HEAD, so the operation can still finalize or recover.
Several clones may write to the same journal. journal pull fetches the
journal branch, reports aligned, ahead, or behind, and stops on
divergence. When behind, it keeps local changes to paths the remote did not
touch, accepts changes that are byte-identical to the remote tip (including
the residue of a fast-forward the ref guard refused), and fast-forwards under a
Syncwheel ref-move authorization. journal publish --apply runs the same pull
first, so a publisher that fell behind catches up instead of stopping. If its
push loses the lease, the unpublished snapshot returns to the working tree and
the next run retries. Raw git merge or git pull on the journal branch stays
refused by the reference-transaction guard.
A path changed differently on both sides is a conflict. The default pull stops
and names it. journal pull --apply --park-conflicts saves each local version
under .git/syncwheel/journal-conflicts/<stamp>/, restores the path,
fast-forwards, and runs a three-way merge. A clean merge lands in the working
tree. An overlapping or binary edit stays parked with ours/, base/,
theirs/, and a conflict/ file with markers, listed in conflicts.json, and
the working tree keeps the remote version. Conflict markers never enter the
working tree, so a scheduled publish cannot record them.
AI agents resolve journal conflicts themselves rather than handing them to a human:
- Run
syncwheel journal pull --apply --park-conflicts. - For each
conflictentry, read the parked versions and write one merged file into the working tree that keeps the intent of both sides. For append-only logs and notes, keep both entries in chronological order. - Run
syncwheel journal publish --apply, then delete the parked directory.
Stop and ask only when the two sides contradict each other in a way that needs a human decision, such as two different values for the same setting.
Common aliases:
check->ckstatus->stvalidate->vplan->plreconcile->recchannel->chstack->s,spokeint->istack create->s newstack rebuild->s rbint rebuild->i rbgitsubcommands ->g--personal->-p
Agents should not infer stack ownership from memory when the repository is meant to be maintained via syncwheel.
Four ratified working rules, in full in the skill and docs/ai-agents.md:
- never author or commit in the primary checkout — open a governed lane with
syncwheel worktree open <lane> [--into <stack> [--base <stack-branch>]] [--full] - never resolve a replay conflict with raw git — retry with
--replay-mode desk, then resolve throughstack absorb/stack resolve-integration - integration composition is declared and visible — check
syncwheel int showbefore testing there or blaming your own code - record a reason for each mutation: pass
--reasonwhere the subcommand's help lists it; otherwise record the reason and command in the work receipt
Recommended sequence:
repo tracking statushandofffor an active-active manifest, otherwisereconcile- update the manifest with
stack sync,stack set, orstack addif the dry-run report shows real ownership changes syncpublishwhen the rebuilt managed branches should become the shared remote state- rerun
reconcileorcheckand report remaining drift honestly
See docs/ai-agents.md.
When .syncwheel/manifest.json is the source of truth for exact stack commits,
do not try to make a manifest-editing commit describe itself inside that same
manifest revision.
Use this rule instead:
- stack commits describe product/runtime changes
- manifest edits and syncwheel-version bumps are control-plane metadata
- rebuild
pr/*branches and integration from the manifest - keep manifest-maintenance commits out of
integration.stacks
For the operational flow, see docs/core-procedure.md.
MIT
Defer unmerged work safely with the proof-bound stack archive lifecycle.
When local unpublished snapshots and new remote commits diverge, preview and apply a recovery before publishing:
syncwheel journal recover
syncwheel journal recover --apply
syncwheel journal publish --committed-only --applyRecovery is journal-only. It fetches remote refs, reports in-sync, ahead-only,
behind-only or diverged, and delegates behind-only updates to journal pull.
Diverged recovery drops a snapshot whose change is already on the journal tip (listed as absorbed, for example after a squash merge) and otherwise refuses snapshots reachable from any advertised remote ref (the refusal names the first and the last published snapshot and their refs),
merge commits, and dirty or obstructing replay paths; it never stashes. It
replays single-parent snapshots in an isolated worktree, retaining author,
committer, dates and message; signatures are removed because the commit changes.
Conflicts name the original commit and paths, and leave the original branch,
index and checkout unchanged. Unrelated local changes are preserved.
Success moves only the local branch through the managed ref guard. A private JSON receipt under the Git directory records the old/new tips, ordered commit map, timestamp and exact rollback command. The rollback requires the exact recovered head and clean affected paths:
syncwheel journal recover --rollback <receipt> --applyRecovery and rollback never push. Review the recovered history before running journal publish. A prepared receipt retained after interruption records the intended transition; inspect the branch before deciding whether rollback is needed.