> ## Documentation Index
> Fetch the complete documentation index at: https://onyxresearch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Start an agent-first Onyx research loop from an existing repository.

This guide takes you from an existing repository to an Onyx agent running measured experiments.

<Info>
  Complete [installation](/docs/installation) before continuing. You should be logged
  in with `onyx login`.
</Info>

## 1. Grant Repository Access

Open the [Onyx app](https://app.onyxresearch.ai), 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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx agent install-skill
onyx agent skill-path
```

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

<Tip>
  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.
</Tip>

## 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:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
/onyx Tune my PID controller gains, minimize tracking error
```

Better prompts include the goal, metric, direction, important files, and constraints:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
/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 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.

| File or state                                 | What it does                                                                                                         |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Campaign                                      | The logical research direction tracked by the Onyx API.                                                              |
| `refs/onyx/experiments/<campaignId>/<runRef>` | The immutable git ref pushed before an experiment can count.                                                         |
| `onyx/setup.json`                             | The canonical local setup policy: goal, metric, scope, protected paths, resources, declared tools, and workflow.     |
| `onyx/validation.json`                        | The latest local validation report with the setup hash and static checks.                                            |
| `onyx/onyx.md`                                | A generated research spec for durable project guidance and constraints.                                              |
| `onyx/tools/*`                                | Helper commands for reset, observe, collect, simulators, hardware rigs, remote services, evaluation, and guardrails. |

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:

```markdown theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
## 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 changing setup intent, ask the orchestrator to restart from Setup:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
/onyx Stop this session, revise the setup with the updated constraints, validate it, and restart Research
```

## 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:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx status
onyx research status
onyx-worker workflow status
onyx listen
onyx-worker exp list --limit 20
```