Skip to main content
In a WSL2 environment, the main agent executing /onyx and all its shell commands must run in the same Ubuntu distribution as the workers. See Windows via WSL2 for qualification status. Onyx is designed to be agent-first. The CLI handles credentials, local runtime files, tool execution, workflow runs, hypothesis workers, immutable ref pushes, and direct API reporting; the /onyx skill uses those primitives as a human-facing orchestrator.

​
Start a New Research Direction

Use /onyx from an agent that has the Onyx skill installed:
The orchestrator should turn that request into a campaign, a repo-side setup, a validated local workflow, deliberate hypothesis plans, and then asynchronous hypothesis workers that run measured experiments and share concise knowledge.

​
Prompt Shape

Short prompts work, but precise prompts help the agent set up better evals.
text /onyx Tune my PID controller gains, minimize error

​
What the Agent Does

1

Clarifies the setup

The agent asks for any missing goal, metric, direction, files in scope, constraints, resources, or stop conditions, then pauses for your approval of those setup inputs before building anything.
2

Creates the campaign

It creates or selects a long-lived Onyx campaign and uses immutable experiment refs for results. The campaign metric contract is immutable.
3

Writes setup.json and onyx.md

It creates the canonical local setup policy and a generated research spec that future agents and humans can read.
4

Declares workflow tools

It declares evaluation, reset/readiness, guardrail, resources, timeouts, output limits, and protected paths in setup. Helper scripts live under onyx/tools/*.
5

Validates setup

It runs local setup validation and writes onyx/validation.json; failed or stale validation blocks Research.
6

Reviews the setup with you

Before committing, it pauses again for your approval of the completed setup, surfacing any concerns or details worth discussing — setup quality directly shapes every downstream hypothesis worker, and setups can involve real hardware.
7

Commits setup

It commits the onyx/ setup surface so every session assignment starts from a commit containing the validated setup, instructions, and workflow tools.
8

Pushes the setup base

In the bundled /onyx workflow, it pushes the setup base commit before remote campaign setup so GitHub-backed code reads can verify the base commit.
9

Plans hypotheses

It creates structured hypothesis plans with focus, hypothesis, starting points, avoid-list, success signals, and give-up signals.
10

Runs hypothesis workers

It starts onyx research run, a local supervisor that always creates a new bounded remote session, snapshots its active hypotheses and starting commits, and asks the server for a worker lease before each provider launch, sends telemetry-only presence updates, ramp-launches workers in batches, and pauses briefly on provider startup or rate-limit failures. New sessions require --experiments, --max-minutes, or both. --experiments is an exact accepted report target owned by the server. Built-in Codex, Claude, and OpenCode workers receive prompts over stdin, isolated runtime directories under .git/onyx/worker-runtime/, worker identity and lease environment variables, and an explicit onyx-worker CLI. They write raw provider logs, readable .activity.log files, structured .activity.jsonl events, per-worker latest-state JSON snapshots, and manifests under .git/onyx/worker-logs/. Workers run measured workflows, make exactly one result commit for a measured attempt, push refs/onyx/experiments/<campaignId>/<runRef>, then report directly to the API. Overflow reports are retained as internal discarded diagnostics, stay hidden from normal product surfaces, and never count toward targets or rankings. If a stop is requested, the harness gives the provider a grace period and then terminates it before its terminal cleanup. The first server transition sets an immutable endedAt cutoff and end reason. Open sessions derive starting, active, stale, or abandoned liveness from telemetry and leases.
11

Adds hypotheses

The human or main-thread orchestrator reviews status, experiments, knowledge, and worker capacity, then adds fresh campaign hypotheses with onyx research hypothesis add. Session membership is immutable, so newly added or reopened hypotheses join the next session. Closing a hypothesis immediately cancels its existing assignments and workers. Workers do not create successor hypotheses themselves.

​
Change Setup Deliberately

onyx/setup.json, onyx/validation.json, onyx/onyx.md, and onyx/tools/* are protected setup paths during Research. If you need to change how agents behave or how measurements work, ask the orchestrator to stop and revise setup instead of asking hypothesis workers to mutate those files. Good steering edits include:
  • add or remove files in scope;
  • add constraints such as “no new dependencies” or “do not change the hardware interface”;
  • define guardrails or readiness checks;
  • summarize approaches that failed;
  • add a new promising idea;
  • set stop conditions.
Then tell the orchestrator:

​
Under the Hood

The agent uses these CLI primitives: Full/orchestrator primitives:
Worker-safe primitives:
You can run both CLIs manually when debugging, but normal users should start from /onyx.