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

# Monorepos and Project Paths

> Scope Onyx to a subdirectory while keeping git history in the full repository.

`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 campaign, set:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
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:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
/onyx Optimize the planner under apps/controller.
Use projectPath apps/controller and maximize score from the setup evaluation tool.
```

The agent will pass the matching project path to the CLI primitives it runs. When debugging manually, use the same path:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx campaign setup \
  --name faster-planner \
  --project-path apps/controller

onyx-worker exp run --campaign faster-planner --project-path apps/controller --auto
onyx-worker exp log --project-path apps/controller --description "initial measurement"
```

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:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
apps/controller/onyx/onyx.md
apps/controller/onyx/setup.json
apps/controller/onyx/validation.json
apps/controller/onyx/tools/
```

The setup files under `onyx/` are protected during Research: `onyx.md`,
`setup.json`, `validation.json`, and `tools/*`.