Skip to main content
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

1

Install the Onyx agent and CLI

The installer logs you in through the browser and adds the /onyx skill to Claude Code and Codex.
2

Grant GitHub access

In the Onyx platform, connect your GitHub account so Onyx can read repository metadata, commits, trees, and diffs.
3

Run Onyx in your agent

Open your repo in Claude Code or Codex and call /onyx with a goal, stop condition, and metric:
Open a new terminal in the same repo and call onyx listen to watch Onyx auto research.
For full setup options and a guided walkthrough, see Installation and the Quickstart.

​
What Onyx Tracks

Project

A repository that already exists. Onyx attaches to your code instead of scaffolding or owning it.

Campaign

A research direction with tasks, workers, metrics, summaries, and immutable experiment refs.

Experiment

A measured attempt at an exact commit, with status, metrics, notes, and diff context.

​
How the Loop Works

1

Grant repository access

Install or manage the Onyx GitHub App so Onyx can read the repository.
2

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

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

Review results

Use the platform graph, timeline, file tree, and diffs to compare attempts and understand best-so-far progress.

​
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

Then, in Claude Code or Codex:
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

Install Onyx

Install the CLI, log in to your team, and verify your local profile.