syncwheel
AI-ready Git coordination v0.43.28

Move atmachine speed.Stay in control.

Syncwheel coordinates every Git lane used by humans, AI agents, CI and delivery systems—without sacrificing review, safety or recovery.

Start building See how it works →
Preview the next Git state before changing it

$ syncwheel validate && syncwheel plan

✓  OK · no actions needed

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

One declared system. Every active PR has a place.

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 replayed, no worktree replayed, no worktree --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, with create-only ref CAS and recoverable ledger intent.

$ syncwheel int rebuild --reason "refresh integration projection"

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

Same changes, same commits: each drifted branch is replayed onto the new base, reproducibly, with a backup first and without creating a worktree.

$ syncwheel publish $ syncwheel stack close feature-a --reason absorbed

Push managed branches, then close a squash or rebase delivery by verified final content. A normal absorbed close does not need --force. Read the exact nested --help before the first mutating subcommand in a session.

$ syncwheel resume

Another device or agent worked? Converge from the ledger.

What it actually is

One control plane.
Every lane.

PR management is only the beginning. Syncwheel separates Git responsibilities into dedicated projections, then coordinates them as one system.

01

Pull requests

One branch. Many PRs. Review each change independently.

clean branches
02

Integration

All active PRs tested together before merge.

system tested
03

Channels

Pin and promote the exact tested composition for deployment inputs.

digest verified
04

Journal

Generation-bound create and close intents let a human or agent recover exactly where work stopped. Absorbed closes bind their proof to a fetched delivery SHA and the composed final content.

state protected

Compose what you deploy. Keep deployment honest.

A channel is an ordered snapshot of exact stack revisions. Syncwheel rebuilds and publishes the Git branch; your deployment platform remains the authority for the environment.

Stacks are review units

Each stack owns the commits and PR branch for one change. Updating a stack does not silently move an existing channel pin.

Integration is the whole workspace

main-integration combines every active stack for daily work. It is disposable and rebuildable, not an environment contract.

Channels are pinned compositions

dev, test, or a preview branch can contain only the selected stack revisions, in a declared order.

Deployment stays external

A published channel proves a Git ref and composition digest. It never claims that a runtime deployed or became healthy.

channel flow 
$ create_plan="$(syncwheel channel create dev --lifecycle shared --stack core-api --operation-id create-dev-001)"
$ create_digest="$(printf '%s' "$create_plan" | python3 -c 'import json,sys; print(json.load(sys.stdin)["planDigest"])')"
$ syncwheel channel create dev --lifecycle shared --stack core-api --operation-id create-dev-001 --plan-digest "$create_digest" --apply
$ add_plan="$(syncwheel channel add dev checkout-v2 --operation-id add-checkout-001)"
$ add_digest="$(printf '%s' "$add_plan" | python3 -c 'import json,sys; print(json.load(sys.stdin)["planDigest"])')"
$ syncwheel channel add dev checkout-v2 --operation-id add-checkout-001 --plan-digest "$add_digest" --apply
$ apply_plan="$(syncwheel channel plan dev --operation apply --operation-id apply-dev-001)"
$ apply_digest="$(printf '%s' "$apply_plan" | python3 -c 'import json,sys; print(json.load(sys.stdin)["planDigest"])')"
$ syncwheel channel apply dev --operation-id apply-dev-001 --plan-digest "$apply_digest" --apply
$ publish_plan="$(syncwheel channel plan dev --operation publish --operation-id publish-dev-001)"
$ publish_digest="$(printf '%s' "$publish_plan" | python3 -c 'import json,sys; print(json.load(sys.stdin)["planDigest"])')"
$ syncwheel channel publish dev --operation-id publish-dev-001 --plan-digest "$publish_digest" --apply

Promotion copies exact tested pins; ephemeral previews expire as visible cleanup candidates and are never deleted remotely by surprise. Read the deployment channel guide.

01SyncwheelCoordinates declared lanes and protected publication.
02GitPreserves history and the exact inputs to every composition.
03AIWorks at parallel speed inside an explicit contract.
04HumanSets intent and approves consequential changes.

Built for human–AI teams: no checkout is authoritative. Agents follow the declared contract, while people retain intent and approval.

Agent contract → Agent procedure →

Go deeper.

Everything advanced lives in the docs.

install.md AI handoff for installing Syncwheel. AGENT.md Concise operating guide for agents. llms.txt LLM-oriented map of the docs. README Quick start and CLI summary. Workflow model Stacks, integration, channels, lifecycle. Deployment channels Pinned compositions, exact plans, receipts, and deployment boundaries. Deterministic model Manifest semantics and validation contract. Branch model Branch roles and safety defaults. Core procedure Deterministic recovery, including atomic restoration of an owned remote ref that disappeared. Manual Git flow The raw Git equivalent. AI agents Behavior contract and agent procedure. The article The narrative version, for everyone.
Quick start

Your first verified plan in minutes.

Install the CLI, create the default manifest for the current repository, then inspect what Syncwheel would change.

CLI Install Syncwheel

Install the command on your machine, then verify the executable before touching a repo.

terminal 
$ uv tool install "git+https://github.com/NestDevLab/syncwheel"
$ syncwheel self status
Initialize Create the default manifest

syncwheel init creates the manifest with the standard base and integration defaults. Repository tracking remains an explicit policy choice.

current repository 
$ syncwheel init
Inspect Preview before changing Git

Validation and planning are read-only until you explicitly apply a reviewed plan.

read-only 
$ syncwheel validate && syncwheel plan
the default flow 
$ syncwheel init                 # create the manifest
$ syncwheel validate && syncwheel plan # inspect, no mutation

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