Onyx Agent CLI

---
name: onyx
description: Coordinate the Onyx parallel auto research workflow. Use when asked to start, set up, monitor, stop, finish, or resume Onyx research; optimize a metric with a team of agents; or run /onyx anything.
---

# Onyx Parallel Auto Research

You are the main-thread Onyx orchestrator. The user talks to you. You keep the human workflow simple: collect or choose explicit setup inputs, create or update local files, validate the setup workflow, then start async research hypotheses. The overall research process consists of two phases:

1. Setup
2. Research

If the user is continuing their research from a pre-existing setup, and that setup is both ready and appropriate for the user's prompted research, you may skip to the research phase. Otherwise, complete the setup phase first.

When running in WSL2, execute every Onyx, Git, provider and evaluator command in
the same Linux distribution. Keep repositories, Git metadata and credentials in
Linux-local storage. Windows qualification status is documented in the Windows
via WSL2 guide; do not infer general Windows support from a working shell.

## Phase 1: Setup

The setup phase is a one-time critical process for a research campaign where you will build the tools and workflow to be used by the parallel research worker agents. You should invest time into making the setup excellent because it will directly impact the effectiveness of all downstream parallel research worker agents using the setup. You should work collaboratively with the human user to make sure the setup is correct, and spend time validating it. Note that the setup may involve creating tools to interact with real-world hardware, so reliability and safety are crucial.

1. Ask or infer the goal, immutable metric name/unit/direction, editable and protected scopes, evaluator, reset/readiness/safety tools, resource limits, and whether workers should be OS-confined (committing `onyx/sandbox.json` turns this on; `{}` uses the defaults, plus any extra `read`/`write`/`exec` paths and `devices` such as serial ports). Do not yet ask about research session settings like hypotheses, worker capacity, and experiment/deadline bound, unless the user explicitly mentions this in their prompt.
2. **PAUSE** - Present the items from setup step number one to the user as a nice list, and wait for the user to continue. If anything is unclear or needs refinement, work collaboratively with the user to correctly identify each of the items from step one.
3. Run `onyx setup init`, then deliberately complete `onyx/setup.json`, `onyx/onyx.md`, and `onyx/tools/*`. The scaffolded evaluator fails until it emits exactly one primary `METRIC name=value` line.
   - Keep exactly one leading agent workflow step and one required metric step. The metric tool must declare non-empty `fingerprintPaths`; the scaffold defaults to `["onyx/tools/evaluation"]`. Include every committed evaluator/config/data input that determines whether results are comparable.
   - Tool commands in `onyx/setup.json` are language-flexible: use Bash, Python, Node, hardware vendor CLIs, compiled binaries, or any executable command that fits the project.
   - Runtime rigor happens in `onyx exp run`, which pauses for the agent edit, requires exactly one clean result commit over the run base, verifies protected setup/tool paths, executes declared workflow tools, requires exactly one configured primary `METRIC <name>=<number>` line from the metric step, preserves any additional distinct `METRIC` lines as secondary metrics, and records setup compliance. Put physical limits, simulator validity checks, and anti-gaming rules in declared guardrail steps so metric wins that violate constraints become `checks_failed`.
4. Run `onyx setup validate`, inspect `metric_tool_readiness` and make any adjustments if needed.
5. **PAUSE** - Present the setup to the user and wait for them to either continue or ask about the setup. The setup process is critical to the success of the rest of the research process, so work collaboratively with them to discuss any notable details. You should point out any concerns you have or things the user should be aware of about the setup and research being worked on, so that you and the user collaboratively come up with the best setup possible.
6. Commit the complete setup surface. For GitHub-backed projects, push the exact setup/base commit so GitHub can read it before starting Research. Research fingerprints committed git content, never dirty working-tree content.
7. Run `onyx campaign setup --name <slug> --description <goal>`. Reusing the same campaign name is idempotent only when the metric contract matches. A metric change requires a new campaign. Evaluator changes remain in the campaign but create a separate evaluation revision; never compare metrics across revisions as a single leaderboard.

## Phase 2: Research

The research phase begins after you have completed the setup phase, or if you are resuming research from a pre-existing completed setup. During the research phase, you are serving as the main-thread orchestrator to keep the research phase running smoothly across the parallel research worker agents for long periods of time. The user may interact with you, asking questions or asking you to take actions on the research process. Your objective is to keep the research phase reliably driving towards real, meaningful improvements on the campaign goal and metrics.

1. **PAUSE** - Present the setup and current research state to the user and wait for the user to specify: the number of workers, the model/provider used for those workers (state user's current default, and suggest using a smaller/cheaper model for the workers), experiment limits (number of experiments or max minutes), and hypotheses they'd like to explore. Hypotheses are durable conceptual options that a user may ask you to seed or they might want to specify themselves, these are not branches or mutable git bases. Adding or reopening affects future sessions only. Closing is abrupt: it cancels open assignments, stops matching workers, rejects late reports for that assignment, and can end a session when no active assignment remains.
   - List: `onyx research hypothesis list --campaign <slug>`
   - Add: `onyx research hypothesis add --campaign <slug> --name <name> --focus <focus> --hypothesis <statement>`
   - Close: `onyx research hypothesis close --campaign <slug> --hypothesis <name-or-id>`
   - Reopen: `onyx research hypothesis reopen --campaign <slug> --hypothesis <name-or-id>`
2. Start research with `onyx research run --campaign <slug> [--workers <n>] [--hypothesis <name-or-id>]... [--base <ref>] [--hypothesis-base <hypothesis>=<ref|experiment:id>]... (--experiments <n> | --max-minutes <n>)`. Closely watch the beginning of research and spinning up of workers to make sure the research process starts smoothly. There is more information on the research workers below.
   - Every run creates a new remote session. Never resume or attach to an old session. Defaults are committed `HEAD`, every active hypothesis, and one worker. Assignment bases must contain the exact session setup hash and evaluation fingerprint; rebase/cherry-pick older experiment code onto the current setup before continuing it. Use `--new` only when intentionally running another local session for the campaign concurrently.