Skip to main content
Onyx treats git as the canonical code record.

​
Branch Naming

Each research direction maps to: 
onyx/{name}
When you start with /onyx ..., the agent chooses a slug from the goal and creates or resumes the matching onyx/{name} branch. You can still use onyx branch create manually when debugging or scripting, but most users should let the agent own branch setup.

​
Append-Only Rule

Each experiment should be a new commit appended to the branch. Avoid:
  • force-pushing;
  • deleting experiment commits;
  • using git reset --hard to rewrite measured history;
  • reusing one commit for unrelated attempts.
This keeps every reported experiment reachable and reviewable.

​
Previous Best Comparisons

The app stores each experiment commit and calculates the previous best commit for the branch. Diff views can then compare a selected attempt to the best result that came before it.

​
GitHub Code Reads

Onyx reads exact trees, blobs, and diffs from GitHub at the requested commit using the linked GitHub App installation. Repository sync records metadata and the default branch head, but the app does not clone repositories in the web/API runtime.