Skip to main content
After you run a prompt like /onyx Tune my PID controller gains, minimize error, the orchestrator turns that goal into a validated local setup, then starts an asynchronous session whose hypothesis workers produce measured git history.

​
From Prompt to Campaign

The orchestrator first converts your prompt into campaign metadata: It then creates or selects an Onyx campaign and records the current git commit as its base.

​
Local Setup

Before changing product code, the orchestrator should create and commit:
  • onyx/setup.json: the canonical local setup policy;
  • onyx/validation.json: the latest local setup validation report;
  • onyx/onyx.md: the generated research spec with durable project guidance;
  • onyx/tools/*: helper scripts for reset, readiness, evaluation, guardrails, or environment control.
Then it validates the setup hash and static checks so future attempts have a stable local measurement policy.

​
Experiment Loop

Each attempt follows the same shape:
1

Start workflow

A hypothesis worker runs onyx-worker exp run --campaign <name> --auto. The CLI creates a durable workflow run using the clean worker HEAD as the base and pauses at the leading agent step.
2

Edit and commit

The worker changes scoped files based on its brief and onyx.md, then makes exactly one clean result commit.
3

Resume workflow

The worker runs onyx-worker exp run --resume --auto. The CLI verifies setup compliance, executes declared workflow tools, parses the primary metric, and stores step logs.
4

Record

The worker logs the terminal attempt with onyx-worker exp log; the CLI resolves the measured attempt from worker context and records status, metric, output summary, setup compliance, and agent notes.
5

Report

It pushes an immutable experiment ref, then reports the result directly to the Onyx API. The server accepts, deduplicates, or rejects the report.

​
What Gets Recorded

Every experiment points to an exact commit and includes:
  • status, such as succeeded, failed, checks_failed, or setup_violation;
  • primary metric value;
  • output summary;
  • optional guardrail result;
  • local setup compliance;
  • agent notes about what was learned.
These records build the campaign review surface and best-so-far view in the app.

​
How to Watch Progress

In the Onyx app:
  • Graph view shows the campaign, experiments, hypotheses, workers, and current best metric.
  • Campaign overview shows campaign setup summary, resources, workers, hypotheses, summaries, stop state, and best-so-far steps.
  • File tree shows changed files plus onyx/ context.
  • Diff view compares an experiment to the previous best when possible.
In the terminal:

​
Manual Debugging

The agent runs the CLI for you, but these commands are useful when debugging a setup:
Use onyx-worker tools run <tool-id> for transient smoke checks. It leaves workflow and measured-attempt state untouched. If the agent cannot measure progress, inspect the declared metric tool in onyx/setup.json. The metric step must print a numeric line such as: