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.

​
What Onyx Tracks

Project

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

Branch

A research direction, tracked as an append-only git branch named onyx/{name}.

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 agent creates the onyx/{name} branch, writes onyx/onyx.md, creates onyx/eval.sh, and records each measured attempt.
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 branch setup, evals, commits, logs, and sync.
  • Metric-first decisions: branches 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.
  • Steerable research memory: edit onyx/onyx.md to adjust constraints, files in scope, strategy notes, or stop conditions as the loop evolves.
  • Offline-tolerant substrate: the CLI queues records in .git/onyx/outbox.jsonl and syncs when credentials and network are available.

​
Quick Example

onyx login
onyx agent install-skill
Then, in your agent: 
/onyx Tune my PID controller gains, minimize tracking error
The agent will ask for any missing details, create or update onyx/onyx.md, build an onyx/eval.sh that emits METRIC name=value, and begin logging experiments.

​
Next Step

Install Onyx

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