From an empty repo to a nightly cycle.

Install

There is nothing to install globally. The CLI runs through npx, which fetches it on demand — the same way the nightly cloud session will invoke it inside a fresh checkout.

node --version            # 18 or newer
cd path/to/your/repo
npx dream-machine init

init scaffolds a dream.config in the repository root and leaves everything else alone. Run it inside the repository you want the machine to dream about — the config describes one target, and one target only.

Write your first dream.config

The config carries the per-repo delta and nothing else. Everything generic — the pipeline, the verdict vocabulary, the authority boundaries — lives in the engine, so what you write here is genuinely small.

{
  "repo": "ruvnet/metaharness",
  "cron": "0 8 * * *",
  "slots": [
    { "deep": "generator-genome",
      "scan": ["router", "turn-credit"] },
    { "deep": "flywheel-promotion",
      "scan": ["evals-verticals", "bench"] }
  ],
  "bonusModuli": { "25": "vertical-packs", "75": "meta-proxy" },
  "controlPlaneProbes": ["node packages/create-agent-harness/dist/bin.js --help"],
  "buildStep": { "cmd": "npm ci && npm run build", "degradeOnWasmFailure": true },
  "evaluatorEntrypoints": { "bench": "experiments/*/run.mjs" },
  "adrTemplate": "metaharness-7-section",
  "competitorList": ["LangGraph", "AutoGen", "DSPy/GEPA"],
  "extraDiscipline": ["adr-250-proof-ladder"]
}

repo

The single target repository this config describes.

cron

When the night runs, in UTC. Stagger it against your other targets so two sessions never contend for the same budget.

slots

The rotation vocabulary. Each slot names one deep surface to investigate properly and a couple of scan targets to sweep. This is what stops the machine from investigating the same thing forever.

bonusModuli

Occasional surfaces, keyed by night number, for areas worth revisiting periodically but not on the main rotation.

controlPlaneProbes

Commands the session runs to confirm the repository's own tooling is alive before trusting any measurement taken through it.

buildStep

How to build the target, and whether a WASM build failure should degrade the night rather than end it.

evaluatorEntrypoints

Where the evaluators live in this repo — the wiring between the pipeline's stages and the backends that actually run them.

adrTemplate

Which ADR shape this repo writes, so a night's proposal lands in the house style instead of a generic one.

competitorList

The field to read during the research stage — the prior art the night is expected to have considered before forming a hypothesis.

extraDiscipline

Repo-specific rules the night must additionally honour, named by their ADR.

Onboarding a third repository is writing one of these. Not forking an 800-line prompt and hand-editing it — which is the maintenance defect the engine exists to remove.

Compile a routine

Compiling turns the config into the full routine prompt. Both copies that used to be hand-synced — the one pasted into the cloud scheduler and the one mirrored in the repository — become outputs of this single build.

npx dream-machine compile

That is the whole point of the compiler: drift between the two copies stops being a reviewable defect you have to notice, and becomes structurally impossible. Re-run compile after every config change and commit the result alongside it, so the mirror is never a stale artifact of a config nobody remembers editing.

How the design proves itself. ADR-0001's test contract requires the compiler to reproduce the existing hand-written prompts byte-identically from their configs. That is the existence proof that the config really captures the full per-repo delta — if a single byte differs, something is still hiding in the prose.

Verify a witness

Every night stamps a witness that binds what it published to the exact code it ran against. The scheme is deliberately plain enough to re-derive by hand:

WITNESS = sha256( sha256(gist) + SESSION_COMMIT )

The gist is the night's published record; SESSION_COMMIT is the commit the isolated session actually had checked out. Hash the gist, concatenate the resulting hex digest with the commit SHA, hash again. Change one byte of either input and the witness no longer matches.

# produce a witness for tonight's gist + commit
npx dream-machine witness stamp

# check a published witness against its inputs
npx dream-machine witness verify

You do not have to take the CLI's word for it. The same two hashes are reproducible with standard tools, which is exactly why the scheme is worth having:

GIST_HASH=$(curl -sL "$GIST_RAW_URL" | sha256sum | cut -d' ' -f1)
printf '%s%s' "$GIST_HASH" "$SESSION_COMMIT" | sha256sum | cut -d' ' -f1

What a witness does and does not prove. It proves that this record and this commit belong together and have not been edited since. It does not prove the measurement was sound — that is what the adversarial critique, the reward-hack scan, and the promotion gate are for. Provenance and merit are separate claims, checked separately.

Read the ledger

LEDGER.md is the only durable memory that survives between nights — each session is a fresh, isolated checkout with no recollection of the last one. Ten columns, one row per night, appended even when the run halts on budget.

npx dream-machine ledger          # parse and print the rows
npx dream-machine ledger verify   # check the schema holds
npx dream-machine tui             # browse the nights interactively

The ledger is not an archive you consult occasionally — it is an input. Before forming tonight's hypothesis, the engine computes learning signals from it deterministically, in library code rather than leaving them for the model to re-derive:

• Duplicate-finding suppression — a question already answered does not get asked again.
• Zero-merge bias — a surface that has produced nothing a human merged in fourteen nights gets weighted down.
• Low-score-streak throttling — a run of poor results narrows the night's ambition rather than escalating it.

A REJECT row is the point, not the consolation. It is a question that was open at dusk and closed by morning, which makes tomorrow's search space smaller and tomorrow's night cheaper. A night that produces a clean REJECT has done its job.

Schedule the nightly run with Claude Code /schedule

The night runs in an isolated cloud session with a fresh checkout — deliberately not as a CI job in the target repository. The loop needs an agentic session that can research and judge, and keeping evolution authority out of the repo's own CI credentials is a security feature, not an inconvenience. In Claude Code, the built-in /schedule command creates exactly this: a cloud routine that fires on a cron, spins up a fresh session against your repo, and runs the pipeline — autonomous research, evaluation, and improvement that compounds.

npx dream-machine schedule dream.config.json \
  --env <your-cloud-env-id> --out routine.json

2 — create the routine. Run /schedule in Claude Code and create a routine on cron 0 9 * * * (UTC) using the body from routine.json.

Recommended: a self-hosting bootstrap. Rather than freeze a prompt, point the routine at a tiny bootstrap that compiles tonight's instructions from your committed config — so the schedule can never drift from the repo:

You are the Dream Machine nightly runner for <owner/repo>, on main.

1. npm ci && npm run build
2. npx dream-machine compile dream.config.json --out /tmp/tonight.md
3. Follow /tmp/tonight.md exactly — the full 26-step pipeline.

Invariants: end in ACCEPT | REJECT | INCONCLUSIVE. Never merge,
never self-promote. Publish a gist + a labelled issue + a DRAFT PR,
and append exactly one row to docs/dream-cycle/LEDGER.md every run.

Always improving. Each night researches the SOTA for tonight's rotation surface, freezes a falsifiable hypothesis, tests it, and — win, lose, or draw — records what it learned so tomorrow's search space is smaller. A night with no model key still runs: it reports LLM_EVAL=blocked, an honest INCONCLUSIVE, instead of faking a result. This very repository runs this loop on itself on cron 0 9 * * *.

Stagger the cron across targets so nights don't collide — the reference routines run at 0 6 * * * and 0 8 * * *. Keep the compiled mirror committed next to your config so anyone reading the repo can see what the scheduler runs without logging into it.