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

# Overview

> Onyx is a git-native auto research platform for hardware teams and AI agents.

Onyx helps you hand a research goal to an AI agent and get back a measured, reviewable history of attempts. Grant Onyx GitHub access to an existing repository, log in to the `onyx` CLI once, then prompt an Onyx-enabled agent with something like `/onyx Tune my PID controller gains, minimize tracking error`. The API is the source of truth for research state, while git stores immutable experiment commits.

## Install and Quickstart

<Steps>
  <Step title="Install the Onyx agent and CLI">
    ```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    curl -fsSL https://onyxresearch.ai/install.sh | bash
    ```

    The installer logs you in through the browser and adds the `/onyx` skill to Claude Code and Codex.
  </Step>

  <Step title="Grant GitHub access">
    In the [Onyx platform](https://app.onyxresearch.ai), connect your GitHub account so Onyx can read repository metadata, commits, trees, and diffs.
  </Step>

  <Step title="Run Onyx in your agent">
    Open your repo in Claude Code or Codex and call `/onyx` with a `goal`, `stop condition`, and `metric`:

    ```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
    /onyx Tune my PID controller gains for 5 iters, minimize error
    ```

    Open a new terminal in the same repo and call `onyx listen` to watch Onyx auto research.
  </Step>
</Steps>

For full setup options and a guided walkthrough, see [Installation](/docs/installation) and the [Quickstart](/docs/quickstart).

## What Onyx Tracks

<CardGroup cols={3}>
  <Card title="Project" icon="folder-git-2" href="/docs/concepts/projects-campaigns-experiments">
    A repository that already exists. Onyx attaches to your code instead of
    scaffolding or owning it.
  </Card>

  <Card title="Campaign" icon="route" href="/docs/concepts/projects-campaigns-experiments">
    A research direction with tasks, workers, metrics, summaries, and immutable
    experiment refs.
  </Card>

  <Card title="Experiment" icon="flask-conical" href="/docs/concepts/projects-campaigns-experiments">
    A measured attempt at an exact commit, with status, metrics, notes, and diff
    context.
  </Card>
</CardGroup>

## How the Loop Works

<Steps>
  <Step title="Grant repository access">
    Install or manage the Onyx GitHub App so Onyx can read the repository.
  </Step>

  <Step title="Ask the agent">
    In an agent with the Onyx skill installed, describe the goal and metric in
    plain language: `/onyx Tune my PID controller gains, minimize error`.
  </Step>

  <Step title="Let Onyx create the research surface">
    The orchestrator creates or selects a campaign, writes the canonical
    `onyx/setup.json` plus the generated `onyx/onyx.md` research spec, validates
    the setup workflow into `onyx/validation.json`, creates deliberate hypothesis
    plans, and starts an asynchronous research session.
  </Step>

  <Step title="Review results">
    Use the platform graph, timeline, file tree, and diffs to compare attempts
    and understand best-so-far progress.
  </Step>
</Steps>

## Why Teams Use Onyx

* **Git-native record**: code stays in your repository and every experiment points to a commit.
* **Agent-first workflow**: describe the research goal once and let the Onyx skill drive local setup validation, parallel hypothesis workers, workflow runs, commits, immutable ref pushes, and direct API reporting.
* **Metric-first decisions**: campaigns declare the metric, unit, and direction that determine best-so-far.
* **Shared review surface**: the app turns local agent work into graph, chart, timeline, file, and diff views.
* **Repo-local setup**: `onyx/setup.json` defines the goal, metric, scope, resources, declared tools, and workflow, while `onyx/validation.json` records the latest local validation evidence.
* **Remote-first control plane**: Supabase/API owns research state, worker leases, and accepted experiment order; `.git/onyx/` holds local runtime logs, manifests, workflow files, attempt files, and resource locks.

## Quick Example

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

Then, in Claude Code or Codex:

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

The orchestrator will ask for any missing details, create or update `onyx/setup.json` and the generated `onyx/onyx.md` research spec, validate setup, and then start asynchronous hypothesis workers that measure, push immutable result refs, report experiments, summarize progress, and publish shared knowledge.

## Next Step

<Card title="Install Onyx" icon="download" href="/docs/installation" horizontal>
  Install the CLI, log in to your team, and verify your local profile.
</Card>