flywheel

Own the factory. Rent the agents and the intelligence.

flywheel is a dark factory for AI coding work: a small Go CLI plus agent skills. The factory
(work orders, gauges, the event log, its memory) is files you own; agents and models are rented
from any vendor and swapped at will. Cheap disposable agents build, deterministic gauges re-measure
every claim, and one frontier lead makes only the critical calls. It is for engineers who run
coding agents in parallel and want every change measured, recorded and recoverable.

See it run: the live demo replays a real session and lets you drive the real factory view.

For agents: agents.html is one page with the roles, the loop as exact commands, the brief format and the rules; llms.txt indexes the docs.

Install

Download flywheel-<version>-<os>-<arch>.zip from the
latest release (Windows binaries ship as
flywheel-<version>-windows-amd64.exe.zip) plus checksums.txt, verify the SHA-256, and put the
binary on PATH renamed to flywheel (the archive holds a single binary named after the release).
Or install with Go (the module is github.com/suzworx/flywheel; the binary lands in
$(go env GOPATH)/bin), or build from source:

go install github.com/suzworx/flywheel/cmd/flywheel@latest
# or
git clone https://github.com/suzworx/flywheel.git && cd flywheel
mkdir -p bin && go build -o bin/flywheel ./cmd/flywheel

flywheel upgrade --check tells you whether a newer release exists and flywheel upgrade
installs it, checksum-verified. It refuses (exit 6) while a run's lease is live in --dir
(default .), since swapping the binary can crash that run; wait for it (flywheel wait) or pass
--force. Then install the skills into your agent, one per skill folder (Skills):

npx skills add suzworx/flywheel --skill flywheel
npx skills add suzworx/flywheel --skill flywheel-worker
# ... flywheel-planner, flywheel-foreman, flywheel-inspector, flywheel-reviewer,
#     flywheel-auditor, flywheel-steward, flywheel-operator

60-second tour

Offline, no API key: the sim adapter replays a recorded worker run instead of calling a model.
In an empty git repository:

flywheel init
flywheel config set workers.default.adapter sim
flywheel config set workers.default.model .flywheel/sim.jsonl
cat > .flywheel/sim.jsonl <<'EOF'
{"type":"text","sessionID":"ses_demo","part":{"type":"text","text":"Wrote hello.txt. Gate passes."}}
{"type":"step_finish","sessionID":"ses_demo","part":{"type":"step_finish","reason":"stop","tokens":{"input":120,"output":40},"cost":0.001}}
EOF
cat > .flywheel/briefs/hello.txt <<'EOF'
owns: hello.txt (new)
needs: none
gate: grep -q "Hello from flywheel" hello.txt

# TASK: hello — write a greeting file

Write hello.txt containing the line "Hello from flywheel". At most one write per response.

## Checks

Report the commands you ran and their real exit status.
EOF
flywheel lint .flywheel/briefs/hello.txt          # 0 problems, 0 warnings
flywheel log --task hello --kind planned --brief .flywheel/briefs/hello.txt
flywheel run hello

hello r1 dispatched sim .flywheel/sim.jsonl
hello r1 finished rc=0 reason=stop model=.flywheel/sim.jsonl steps=1 tokens=160 cost=$0.0010
hello r1 finished without writing a file
hello r1 never ran gate(s) 1

The worker says the gate passes. The gauges measure instead of believing it:

$ flywheel validate hello                                  # exit 5
hello gate 1: failed (rc=2)
hello note: the worker never ran gate(s) 1 itself; its report's claims about them are unmeasured
hello owns: ok
$ flywheel inspect hello --verdict pass --session lead-1   # exit 6
flywheel inspect: T3: no passing supervisor validated reading for gate 1 on tree 4b825dc642cb6eb9a060e54bf8d69288fbee4904 after the latest finished event; run: flywheel validate hello
$ echo "Hello from flywheel" > hello.txt
$ flywheel validate hello                                  # exit 0
hello gate 1: pass (399ms)
hello owns: ok
$ flywheel inspect hello --verdict pass --session lead-1   # exit 0
hello inspected pass
$ flywheel factory --once
units (1)
  TASK               STAGE     ATT  SESSION      MODEL                    STEPS   AGE RUN
  hello              passed    r1                .flywheel/sim.jsonl         1    0s done

With a real worker (claude, codex, opencode or pi) the file is written by the agent; see the
Quickstart for the full path to a landed unit.

Docs

The site renders all of these: suzworx.github.io/flywheel.

• Quickstart — from a binary to one landed unit through the loop.
• Concepts — work orders, owns:, gates, the event log, the poka-yoke rules.
• Protocol — the normative contract: every event kind, rule and exit code.
• Features — the long walkthrough: adapters, routing, limits, recover,
  worktrees, the review agent and panel, freeze and resume, the wake schedule, ship.
• Factory screens (docs/screens.html)
  — the approved k9s-style design for flywheel factory, each screen marked shipped, building or
  planned.
• HUMAN.md — leading the agents yourself from the terminal.
• Design docs:
  • Autonomous shipping — the factory model, the required
    events, the poka-yoke transition rules, and the enforcement layers.
  • Flywheel at scale — personas, many parallel workers,
    per-task worktrees and landing, native feedback, and offline use.
  • Factory as files
  • Runtime: architecture,
    gaps, design,
    plan
• Review calibration — the review agent measured against past PRs.
• Skills — one skill folder per factory role; AGENTS.md holds the house rules.

Built by flywheel

Flywheel is built by flywheel. Sujeet (@suzworx) runs its
development as a dark factory.

• From v0.3.0 on, flywheel's own features (flywheel run, the gauges validate, inspect and
  verify, the flywheel factory view), the CLI help and flag fixes, and the factory design
  docs were built as work orders by disposable OpenCode workers on DeepSeek v4 flash (variant
  max).
• Since September 2026 the workers are claude-haiku-4-5 agents dispatched through the claude
  adapter, and the lead is Claude. Across 30 units (33 attempts) a unit cost a median $0.55
  (range $0.27-1.63) and took a median 14 minutes; every attempt finished cleanly, yet the
  lead's review and an independent PR reviewer still caught defects in most units, which is
  why every claim is re-measured rather than trusted.
• Each work order is a brief with owns:, needs: and gate: lines. flywheel's own gauges
  re-run the gates on the exact tree hash and check owns:; inspection and flywheel verify
  (rules T1, T3, T4, T5 and T8) gate every commit. Workers never commit.
• One frontier lead seat outlines work orders, reviews diffs, runs checks against the built
  binary and signs off. The lead seat changed hands between vendors mid-project and the work
  continued from the files.
• Measured worker cost: the CLI help and flag work took 7 units, 1.7M tokens and $0.33; a
  design doc was drafted, corrected and extended by 5 units for about $0.03; a code unit costs
  $0.03-0.08 and takes 15-29 minutes.

The house rules the workers follow are in AGENTS.md.

The factory

Flywheel is a factory for AI coding work: a small Go CLI plus agent skills that run a durable
orchestrator-to-worker loop. A frontier lead agent plans, briefs and judges; cheap disposable
worker agents (Claude Code, Codex or OpenCode) do the reading, writing and testing. The control plane dispatches
work and enforces policy; the data plane keeps traceability, telemetry and accountability for
every session.

Roles

A unit's path

flowchart LR
    WO["Work order"] --> W["Worker (agent CLI)"]
    W --> G["Machine gauges"]
    G --> I["QC inspector"]
    I --> A["Auditor (first articles, samples)"]
    A --> L["Landing"]
    I -. "rework" .-> W

Set up, run, watch

• Set up — flywheel init scaffolds flywheel.md plus the .flywheel/ state files and ends
  with a factory summary: worker lines, limits, audit policy and the enforcement layers installed
  (with the command for each missing one). The default worker uses the first agent CLI it finds
  on PATH (claude, opencode, codex, then pi: npm install -g @earendil-works/pi-coding-agent,
  models provider/id), or the one --adapter NAME chooses. The full factory is
  epic #69.
• Run — the lead records each work order with flywheel log --kind planned; flywheel run
  dispatches it through the claude, codex, opencode, pi or sim adapter and records the run;
  --worktree builds each unit in its own .flywheel/worktrees/<task> on branch fw/<task>.
• Watch — flywheel state derives the floor from the log, flywheel factory opens an
  interactive k9s-style view of it, flywheel watch streams every event as one line, and
  flywheel wait <task>... blocks until the named units finish. In the view, :pulse and
  :metrics chart the metrics and drill to the units behind each number
  (factory view); flywheel fleet status merges every factory on the
  machine into one table (fleet).

The details (bases, --notify, the TREE column, withdrawing a plan) are in
docs/features.md. The planned screens of the factory
view, each marked with what exists today, are on the screens page.

• Set up — flywheel init scaffolds flywheel.md plus the .flywheel/ state files
  (available in v0.2.0). It ends with a factory summary — the worker lines, limits, audit policy, which enforcement layers are installed (and the command for each missing one) and how to view the floor. Building the full factory — lines, staffing, and the policy that keeps it
  safe — is epic #69.
• Run — the lead records each work order as an event with flywheel log --kind planned;
  flywheel run dispatches it to a worker through the claude, codex, opencode or pi adapter and
  records the run automatically. For parallel units flywheel run --worktree is the default: each
  unit builds in its own .flywheel/worktrees/<task> on branch fw/<task>, against the main ledger.
  --worktree --base REF branches a new fw/<task> from REF, without checking REF out. Without
  --base a new fw/<task> starts from origin/<integration.branch> (else the local branch) when
  integration.branch is set, and is refused when neither resolves; otherwise from the main
  checkout's HEAD, with a warning when HEAD carries commits origin/main lacks (#550). The
  dispatched event's base records the commit the unit branched from.
  flywheel run --workdir PATH runs the worker in an existing tree the lead prepared (a merge in
  progress, say) while events still go to --dir's ledger; it is refused (exit 6) with --worktree
  or --base, or when PATH is not a git working tree of the same repository.
  flywheel run --session ID (default $FLYWHEEL_SESSION) records the dispatching lead session as
  the dispatched event's lead, so leads sharing one ledger can tell their units apart.
• Watch — flywheel state derives the floor from the event log; flywheel factory opens an interactive, k9s-style view of the floor (:units :workers :andon :events :lines to switch, / to filter, enter to explain a unit, l for its log, ? for help, q to quit; --plain keeps the plain redraw), and flywheel watch streams every event as one readable line.
  When any unit runs in a worktree, the plain floor's (flywheel factory --plain) units table adds a TREE column with that worktree and its base commit (CP-A@abcdef1), and the --json view carries workdir and base.
• Know when a unit finishes — never background a dispatch with a bare & and hope to notice:
  flywheel wait <task>... [--timeout D] blocks until each named task finishes its current (or
  first) attempt, printing <task> <attempt> finished reason=<r> as each lands (exit 0 all clean,
  4 any unclean, 8 timeout), and flywheel run <task> --notify CMD runs CMD through the shell
  when the run returns on any path, with FLYWHEEL_FINISHED="<task> <attempt> reason=<r> exit=<code>"
  in its environment; a failing notify only warns.

Design priorities, in order: efficiency and consistency, then speed, reliability and
recoverability — the lead spends tokens only where judgment is needed, gauges and telemetry cost
no tokens, and everything replays from the log after any crash.

Why flywheel

Frontier-quality results at a fraction of frontier cost — measured, not promised: the field run
behind the skills used 99 worker runs across 44 tasks, up to 7 workers in parallel, and about
90 % of all worker input across the field run served from the model cache. max_parallel caps
concurrent workers, not concurrent gates: units whose gate: lines name the same expensive
command serialise on it, and the contention manufactures false findings (phantom timeouts) that
read as code defects — flywheel run prints a shared-gate warning at dispatch whenever an
in-flight unit declares the same gate line.

The goal is to ship with no human in the loop. That is only safe if every step is recorded (an
append-only event log), measured by the machine (gauges run by the CLI, never self-reported by
an agent), and audited by independent checkers. Today all three are in place: the append-only
event log is hash-chained, so an edited record, or one removed from the middle, is detected
(flywheel verify --log; cutting records off the end needs an outside anchor such as a pushed
commit); the gauges validate, inspect and verify measure
every unit, with flywheel supervise measuring each finished unit nobody has measured yet; and
flywheel audit re-measures a unit in a clean copy from a session that neither built nor inspected
it, selecting first articles and seeded samples
(#61). Enforcement sits in more than one layer:
the CLI refuses illegal transitions (exit 6), an agent Stop hook runs flywheel gate, and git
hooks check every commit and push (flywheel init --git-hooks); whatever the worker's adapter,
flywheel run flags an attempt that moved HEAD, switched branch or stashed with a git-write
signal, which blocks landing until the lead triages it (it compares the attempt's end points, so a
push or a write undone before exit needs the command-level guard,
#319). That guard is in place: flywheel run
puts a git shim first on the worker's PATH that passes only read-only commands (status, diff, log,
show, grep, blame, rev-parse, … and the listing forms of branch, tag, config, stash) to the real
git and refuses everything else — commit, push, stash, reset, checkout, add, rm, clean, an alias —
in the unit's repository (git in a test's own temporary repository runs normally, and flywheel's
temporary-index tree hashing is allowed), and a run whose guard cannot be installed is refused; a worker that calls git by an absolute path
bypasses it, and the end-point check still applies.

Any agent can lead. The loop lives in repository files and shell commands, not inside any one
vendor's session, so a new head — Claude Code, Codex, OpenCode, or a human — reads the same state
and continues the same work.

How it works

The loop is five steps: Plan → Brief → Dispatch → Review → Correct-or-land. Steps 1, 4 and 5
are lead judgment; 2 and 3 are mechanical.

Repo is the session. All state lives in the repository as files — the event log, work orders,
worker plans, reports — not inside any vendor session. That is what makes agents swappable and the
loop crash-safe: run out of tokens, hit a host timeout, lose a watcher; the next head reads the
same files and continues, and nothing is lost.

1. Plan — the lead turns a goal into work orders: a brief with owns:, needs: and gate:
   lines (flywheel brief --from-issue N writes one from a tracker issue), recorded planned.
2. Brief — flywheel lint checks each brief before it is dispatched.
3. Dispatch — flywheel run sends it to a worker, in its own worktree, and records the run.
4. Review — the gauges (validate, inspect, verify) re-measure every claim; the review
   agent and its panel read the diff (flywheel review --agent).
5. Correct or land — a correction delta goes back to the worker's session, or the unit lands
   (flywheel land --merge) and ships (flywheel ship).

flywheel recover starts every lead session: it checks the ledger against the world and prints
one next action per unit. Adapters, routing, budgets and rate limits, the controller, checkpoints,
worktree setup, the review panel and more, with screenshots, are in
docs/features.md.

To stop the whole factory, flywheel suspend --session S --reason TEXT freezes it: every dispatch
refuses, flywheel next offers no dispatch, and the controller's auto-resume of rate-limited units
starts nothing, while flywheel status and the floor's andon say so first. flywheel resume --session S thaws it (or --until thaws it at a set time); the ledger keeps both records. With
--stop the running workers stop too, each at its next lease tick: the attempt finishes
suspended (exit 6) with its owned files checkpointed and its session kept, and flywheel resume
continues each one in its own session (--no-redispatch only thaws).

The controller does this by itself when the tokens run out: once every configured worker model is
paused by a rate limit, a tick suspends the factory with --stop until the earliest reset
(froze: tokens exhausted until HH:MM), and the first tick past that reset thaws it and resumes
every stopped and rate-limited unit exactly once, each in its own session (thawed: tokens returned; resumed <task> <attempt>). With flywheel schedule install this needs no live process.
A manual flywheel suspend thaws only by flywheel resume or its own --until, and the
controller never re-dispatches its units;
controller.auto_freeze: false turns the automatic freeze and thaw off.

Drive it with a lead agent

Ask your lead agent to load the flywheel skill and drive the loop: plan → brief → dispatch →
review → correct-or-land. The lead writes precise bounded briefs, dispatches workers through the
configured adapter, and judges the evidence. flywheel run records each dispatch automatically;
the lead records the other events (reviews, landings) with flywheel log and the commands below.
Leading the agents yourself from the terminal instead? HUMAN.md walks you through it.

Upgrading

• Swap the binary; renaming the old executable is safe while a unit runs.
• Keep symlinked skill installs rather than copies — the skills installer can replace symlinks
  with copies.
• Commit skills-lock.json, or any tracked file the skills installer touched, before the next
  flywheel validate, because files the lead changes after a unit's dispatch count against that
  unit's owns check. A lead-side edit made after dispatch can be declared afterwards with
  flywheel claim-edit --paths <p1,p2> --session <session>, so the owns check attributes it
  instead of refusing the unit; the claim is bound to the content it declared, so a later change
  to the same path is outside again (issue #258). Another session's edit in a sibling worktree is
  claimed the same way with --worktree <dir>, which hashes the paths in that worktree (issue #362).
• Run flywheel status afterwards.

CLI

One row per command; flywheel help <command> (or <command> -h) prints its usage and every flag,
and exit codes are in PROTOCOL.md. Bare flywheel opens the factory view.

Skills

Each role ships as a skill folder any agent can load:

• flywheel — the lead: drive the loop, judge evidence, never implement.
• flywheel-planner — write work orders; never dispatch.
• flywheel-foreman — run a line of workers; retry by policy.
• flywheel-worker — execute one brief, run its gates, report evidence.
• flywheel-inspector — QC verdicts: pass, rework, scrap, escalate.
• flywheel-reviewer — independent diff review: findings with a failure scenario, never a pass.
• flywheel-auditor — independent audit of first articles and samples.
• flywheel-steward — turn signals and nonconformances into learnings.
• flywheel-operator — install, configure, assign personas.

CI/CD

• ci runs on every PR and push to main: build, vet and tests on Linux, Windows and macOS,
  gofmt, a cross-compile of all release targets, a JSON parse check, and a PR-title check.
• scale CI job drives 1,000 simulated tasks in one ledger twice: through flywheel run
  (TestScaleWave), and through the whole loop — next picks, run dispatches, the gauges
  measure, a lead session inspects and lands, and the log is read back as flywheel watch reads it
  (TestScaleFactoryLoop) — checking no double dispatch, every task landed, no lead escalations and
  an intact hash chain (FLYWHEEL_SCALE=1000 go test -run TestScale ./internal/flywheel/).
• release keeps one release PR open; merging it tags vX.Y.Z, publishes the GitHub release,
  and attaches binaries for five platforms plus checksums.txt.
• Bump rules, highest wins: type! or BREAKING CHANGE: → major (minor while major is 0);
  feat → minor; fix/perf/docs/refactor/revert → patch; anything else → no release.
  PRs are squash-merged, so the PR title decides the bump. The release PR is opened by GitHub
  Actions, so CI checks do not run on it (a GITHUB_TOKEN limitation).
• watch monitors feedback channels persistently without checking out code: when
  devin-ai-integration[bot] submits a review or comment on a PR, it adds the review-findings
  label, and an hourly reconcile (also run on every push to a PR from this repository) adds or
  removes that label so it matches whether the bot still has unresolved review threads. When a
  ci run for a push to main in this repository fails, it opens an issue titled "CI failing on
  main" with the run URL and commit details, or comments on the open one; when a later push run
  succeeds and is still the latest completed run on main, it closes that issue with the recovery
  run URL, so the issue records the whole episode. Incident jobs are serialised, so a failure and
  a recovery never race. PR runs and branches named main in forks never open an incident.
  (Watching a consumer project's local learnings file, outside this repository, still requires a
  person or a persistent session.)

Review threads

A unit's review is read in .flywheel/reviews/<task>.md, a local markdown file flywheel
regenerates from the event log after every agent review round, every worker answer and every
dismissal (#389): one section per round with
each finding, its current status (open, closed, re-reported or dismissed) and the worker's
fixed/disputed answers, then the open blocking findings. It is a generated view, never edited
by hand and never posted to GitHub; the ledger is the record. While a blocking finding is open,
flywheel inspect --verdict pass is refused (rule review), flywheel verify fails R1 for a
pass recorded anyway, the floor's andon shows review-open (<count>), and flywheel stats
reports the review numbers.

Learnings

Consumer repos keep their learnings in .flywheel/learnings.md — the log of what hurt, so friction
becomes spec, curated from signals with flywheel feedback (flywheel feedback regen rebuilds it
from the event log, #38). This repo gitignores that file and tracks
its own learnings as issues under epic #10.
A learning is scoped flywheel (the default; the only kind feedback export/submit send upstream)
or project (feedback add --scope project, kept local), and a journal line is a flywheel log --kind note,
never a learning (#409).

Roadmap

Three epics drive the factory:

• #10 — the factory core: the append-only event
  log, project config, and built-in feedback.
• #35 — flywheel at scale: native feedback,
  personas, many workers, offline.
• #51 — autonomous shipping: a unit's full path
  from work order to landing, with no human in the loop.

License

MIT — see LICENSE.