Skip to main content

clockwright

clockwright is a discrete-event simulation engine built for one purpose: to be the verifier an AI agent optimises against.

See it decide somethingA worked example, the measured numbers, and how to request access — on clockwright.dev

If you are searching over factory or process designs — by hand, with a heuristic, or with an AI agent proposing changes — you need something that can answer "is variant B actually better than variant A?" faster than the search can generate variants, and with an answer you can trust enough to act on. That is the whole job clockwright does.

The one-paragraph thesis​

A simulation is not valuable because it is a perfect replica of a real factory — it never is. It is valuable because it is consistent: run the same model twice and get the same answer, run two close variants and get a reliable ranking between them, and run a proposed change enough times to know whether the difference is real or noise. clockwright is built around that weaker, more honest claim. It ranks variants reliably even where its absolute numbers are off from a real process — which is a much lower bar than fab-grade fidelity, and the one a search actually needs. An engine that is occasionally wrong about the absolute cycle time but always right about which of two designs is faster is exactly as useful to an optimisation loop, and considerably easier to build and to trust.

That distinction shows up everywhere in how clockwright works:

  • Every run is deterministic given the same model, seed and replication count, and that determinism is the thing that makes a verdict reproducible rather than anecdotal.
  • Every comparison between two models produces one of four honest outcomes — better, worse, no meaningful difference, or insufficient evidence — rather than a bare number that looks precise and is not.
  • Every run can be checkpointed and resumed, because a verifier that cannot survive a power cut on a long run is not one you can build a real search loop around.

Who this is for​

clockwright is for anyone who needs to know whether a change to a process — a factory floor, a job shop, a service counter, anything that can be described as resources, routes and arrivals — is actually an improvement, before committing to it in the real world:

  • Process and industrial engineers evaluating a capacity change, a dispatch rule, a staffing plan, or a layout, and who need a number with a confidence interval attached to it rather than a single run's output.
  • People and teams building optimisation loops — search, genetic algorithms, or an AI agent proposing model variants — who need a fast, deterministic, resumable oracle to score each candidate against.
  • Anyone validating a model against known mathematics. clockwright's own test suite is built against closed-form queueing results (M/M/1, M/M/c, Erlang C, and more) precisely because a discrete-event model has no compiler for its semantics — a wrong queue discipline does not crash, it shifts a result by a few percent and looks like an answer.

What this documentation covers​

  • Getting started — obtaining the cwright binary and running your first model.
  • The Model — every keyword, with worked examples
  • Concepts — the determinism guarantees, how experiments and comparisons work, and checkpointing.
  • CLI reference — every command, with its real flags.
  • Reference — the results document, the flow-record schema, and what the engine has and has not yet been validated against.