Skip to main content
projectPath scopes the research surface inside a larger repository.

​
When to Use projectPath

Use it when:
  • the relevant code lives under one package or app directory;
  • multiple Onyx projects should share one monorepo;
  • agents should only see paths relative to a subdirectory;
  • file trees and diffs should stay focused.
Leave it empty when the whole repository is the research surface.

​
App Setup

When starting a branch, set: 
projectPath = apps/controller
Onyx stores projectPath on the auto-provisioned project, prepends it for GitHub code reads, and strips it from file paths returned to the app.

​
Agent Setup

Tell the agent which subdirectory is in scope: 
/onyx Optimize the planner under apps/controller.
Use projectPath apps/controller and maximize score from ./onyx/eval.sh.
The agent will pass the matching project path to the CLI primitives it runs. When debugging manually, use the same path: 
onyx branch create \
  --name faster-planner \
  --metric score \
  --direction maximize \
  --project-path apps/controller

onyx exp run --project-path apps/controller
onyx exp log --project-path apps/controller --description "baseline"
The CLI stores the project path in local state so later commands can infer it.

​
Repo-Side Files

For a scoped project, Onyx files live under the project path: 
apps/controller/onyx/onyx.md
apps/controller/onyx/eval.sh
apps/controller/onyx/checks.sh
Only eval.sh and checks.sh are protected during measurement.