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 branch 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 branch.

​
2. Install the Agent Skill

Run this once for your local agent environment: 
onyx agent install-skill
onyx agent skill-path
The skill teaches the agent how to create Onyx branches, write the repo-side onyx/ files, run evals, log experiments, and push or sync results. By default this installs the Claude Code personal skill at ~/.claude/skills/onyx/SKILL.md, so Claude Code can invoke it as /onyx.
If you are developing the Onyx agent package itself, use onyx developer link . and onyx developer use dev; developer mode switches the managed skill file 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: 
/onyx Tune my PID controller gains, minimize tracking error
Better prompts include the goal, metric, direction, important files, and constraints: 
/onyx Improve the path follower in src/control/pid.ts.
Minimize mean absolute tracking error from ./scripts/evaluate_controller.sh.
Keep overshoot below 5% and do not change the hardware interface.
The agent will ask for missing details when it cannot infer them safely.

​
4. What the Agent Creates

The Onyx agent sets up the research surface for you.
File or branchWhat it does
onyx/{name}The append-only git branch for this research direction.
onyx/onyx.mdThe shared research brief and memory for future agent runs.
onyx/eval.shThe measurement entry point. It prints METRIC name=value lines.
onyx/checks.shOptional correctness checks that run after a passing eval.
You usually do not need to create these by hand. The agent creates an initial version, commits it, runs a baseline, and starts experimenting.

​
5. Steer the Loop with onyx.md

onyx/onyx.md is the best way to steer ongoing auto research. Edit it when you want to change:
  • the objective;
  • the primary metric or secondary monitors;
  • files the agent may edit;
  • files or behaviors that are off limits;
  • correctness constraints;
  • stop conditions;
  • lessons from what has already been tried.
Example steering edit: 
## Constraints

- Do not change the public `MotorCommand` interface.
- Keep overshoot under 5%.
- Prefer simple gain-scheduling changes before adding new dependencies.

## What's Been Tried

- Higher `ki` reduced steady-state error but caused overshoot.
- Filtering derivative error helped noise but made response too slow.
After editing onyx.md, ask the agent to continue: 
/onyx Continue this branch using the updated constraints in onyx/onyx.md

​
6. Watch Results in Onyx

As the agent runs, open the project in the app:
  • Graph view shows research branches and best metrics.
  • Branch timeline shows every experiment.
  • File tree shows changed files plus the onyx/ context.
  • Diff view compares attempts against previous best results.
You can also inspect local state: 
onyx status
onyx exp list --limit 20

​
Next Steps

Use Onyx with agents

Learn the full agent runner contract behind /onyx.

Understand onyx.md and eval.sh

Learn how the agent creates and uses the repo-side research files.