Skip to main content
This guide takes you from an existing repository to an Onyx agent running measured experiments.
Complete installation before continuing. You should be logged in with onyx login.

​
1. Grant Repository Access

Open the Onyx app, sign in, and make sure the Onyx GitHub App has access to the repository you want to optimize:
  • Install or manage the GitHub App for the GitHub account or organization.
  • Grant access to the repository.
  • For monorepos, use projectPath when starting the campaign so Onyx tracks the relevant subdirectory.
Onyx attaches to a repository that already exists. It does not scaffold a new repo. The internal project is created automatically the first time you start an Onyx campaign.

​
2. Install the Agent Skill

Run this once for your local agent environment:
The skill teaches the agent how to act as the Onyx orchestrator: create campaigns, write the repo-side onyx/ setup files, validate the local workflow, launch parallel hypothesis workers, push immutable result refs, and report results directly to the Onyx API. By default this installs managed Claude Code and Codex skill files, so either agent can invoke it as /onyx. The managed targets are ~/.claude/skills/onyx/SKILL.md, ~/.agents/skills/onyx/SKILL.md, and ${CODEX_HOME:-~/.codex}/skills/onyx/SKILL.md.
If you are developing the Onyx agent package itself, use onyx developer link . and onyx developer use dev; developer mode switches the managed skill files to the linked checkout automatically. Active agent sessions may need to reload or restart if they cache skill files.

​
3. Start with /onyx

Open your repository in an Onyx-enabled agent such as Codex, Claude Code, Pi, or Cursor. Then give the agent a goal:
Better prompts include the goal, metric, direction, important files, and constraints:
The orchestrator will ask for missing details instead of guessing the editable scope, evaluation command, or source files. It then runs Setup, writes and edits onyx/setup.json, validates the setup workflow into onyx/validation.json, commits the setup base, and starts Research once validation has no failed checks.

​
4. What the Agent Creates

The Onyx agent sets up the research surface for you. You usually do not need to create these by hand. The orchestrator creates an initial explicit scaffold, edits the setup files and tools for the task, validates them, commits the setup surface, and then starts hypothesis workers.

​
5. Change Setup Deliberately

onyx/setup.json defines the research setup. During Research, hypothesis workers treat these setup files as frozen:
  • onyx/onyx.md;
  • onyx/setup.json;
  • onyx/validation.json;
  • onyx/tools/*.
If you need to change the objective, metric, reset behavior, evaluation, or guardrails, stop the session and ask the orchestrator to revise and revalidate setup. Use setup updates for:
  • the objective;
  • the primary metric;
  • files the agent may edit;
  • files or behaviors that are off limits;
  • workflow tools, guardrail steps, or resource leases;
  • correctness constraints;
  • lessons from what has already been tried.
Example steering edit:
After changing setup intent, ask the orchestrator to restart from Setup:

​
6. Watch Results in Onyx

As the agent runs, open the project in the app:
  • Campaign graph shows experiments, hypotheses, workers, and provenance links.
  • Campaign overview and metric views show campaign setup summary, resources, workers, hypotheses, knowledge, summaries, stop state, and metric projections.
  • File tree shows changed files plus the onyx/ context.
  • Diff view compares attempts against previous best results.
You can also inspect live research state and local runtime files: