> ## Documentation Index
> Fetch the complete documentation index at: https://cli-docs.relai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# optimize

> Reference for relai optimize.

`relai optimize` improves the agent against selected learning environments and registered benchmarks.

```sh theme={"system"}
relai optimize [OPTIONS]
```

<Warning>
  Optimization can take a while depending on agent complexity, selected environments, and `--total-rollouts`. RELAI uses 1/3 of total rollouts for the optimization loop and reserves 2/3 for final before/after evaluation.
</Warning>

## Select behavior

| Option                    | Description                                                                                         |
| ------------------------- | --------------------------------------------------------------------------------------------------- |
| `--learning-envs {NAMES}` | Learning environment names. May be repeated or comma-separated.                                     |
| `--tags {TAGS}`           | Tags selecting learning environments. May be repeated or comma-separated.                           |
| `--benchmarks {IDS}`      | Registered benchmark ids. May be repeated or comma-separated.                                       |
| `--seed-envs {NAMES}`     | Seed learning environment names used for warm-start scheduling. May be repeated or comma-separated. |
| `--agent-target {TARGET}` | Named target to optimize. Required when multiple targets are registered.                            |

Optimization applies to one target at a time. In a multi-target repository,
pass `--agent-target {target}` rather than applying the selected environments or
benchmarks across every agent.

## Runtime

| Option              | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `--env-file {PATH}` | Load simulator runtime variables from a `KEY=VALUE` file. |
| `--env {KEY=VALUE}` | Set one simulator runtime variable.                       |

Optimization runs simulations, so configure required runtime values as
described in [Environment variables](/cli/simulate#environment-variables).

## Optimizer controls

| Option                     | Default                                       | Description                                                                                                                                                                                                         |
| -------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--total-rollouts {COUNT}` | interactive default `max(30, 6 * batch-size)` | Total simulator rollouts. RELAI uses 1/3 for optimization and reserves 2/3 for final before/after evaluation. Non-interactive runs use the same default when omitted. Minimum: `6 * batch-size`. Current cap: 1000. |
| `--batch-size {COUNT}`     | `1`                                           | Environments or tags per optimizer turn. Current cap: 10.                                                                                                                                                           |

### Sizing a run

Every selected sample is evaluated at least once before RELAI's scheduler
starts prioritizing the weakest ones, so a large benchmark spends much of a
small rollout budget on its first full pass. For quick iteration against a
large suite, register a subsample — especially the cases you already know
fail — and keep the full benchmark for occasional complete passes. When most
samples are genuinely challenging, there is no good subsample: give the run a
larger rollout budget and let it fix as much as the budget allows.

Prefer a smaller `--batch-size` when single runs of your agent produce long
trajectories — long conversations, deep tool-call or reasoning chains — since
each optimizer turn has to reason over every trajectory in the batch. When
each simulation is short and fast, a larger batch size is more efficient.

## Optimizer scope

Before optimization starts, interactive runs ask you to review the optimizer
scope: the guardrails that define what kinds of changes RELAI may make to your
agent. RELAI shows the current scope and lets you proceed or edit it. The
confirmed scope is saved to `.relai/optimizer-scope.json` and reused by later
non-interactive runs.

The scope controls:

* `Allowed changes`: choose `Prompt/config only` when RELAI should stay limited
  to prompts, instructions, configuration values, and model settings. Choose
  `Structural changes allowed` when RELAI may also change code, workflow
  structure, and tools.
* `Model changes`: choose whether RELAI may change the AI models currently used
  by the agent. By default, model changes are not allowed.
* `Allowed models`: when model changes are allowed, list the exact replacement
  model candidates RELAI may use. At least one model is required before RELAI
  can proceed with model changes enabled.
* `API-key-backed tools`: choose whether RELAI may add new tools or integrations
  that require external credentials or may incur cost. By default, these are not
  allowed.

The default scope allows structural changes, keeps the current models fixed,
and does not allow new API-key-backed or potentially paid tools. Edit the scope
when a run should be narrower, such as a prompt-only pass, or broader, such as a
run where model changes are acceptable within a specific candidate list.

Non-interactive optimization requires a saved optimizer scope. If
`.relai/optimizer-scope.json` does not exist yet, run `relai optimize`
interactively once to confirm it.

## Evaluation during optimization

You do not need to run [`relai simulate`](/cli/simulate) before optimizing.
Each optimizer run evaluates the agent itself: the reserved 2/3 of
`--total-rollouts` pays for a "before" evaluation pass at the start and an
"after" pass that verifies the final changes. Earlier simulation results are
not reused.

Optimizer evaluations run through the simulator, so each rollout scores the
selected environment's or benchmark's own evaluators plus every
[global evaluator](/cli/evaluator#how-global-evaluators-are-applied) whose
scope matches the simulation. When an evaluator already scores perfectly in
the "before" pass, there is nothing for the optimizer to fix for it, and the
agent is left unchanged in that respect.

Candidate changes are accepted only when the overall evaluation result
improves. RELAI weighs evaluators against each other — a large gain on one
with a slight regression on another can pass, while trading equal gains for
equal losses cannot — and reviews whether the change is sensible overall
rather than applying a purely numerical threshold. A candidate that causes a
regression is rejected, and the optimizer records the lesson and tries a
different approach. When no candidate survives, the run reports that it could
not improve the agent and finishes with no accepted changes and no PR.

## Where optimization happens

`relai optimize` never edits your checkout directly. Each run prepares a
separate git worktree under `~/.relai/worktrees` at your current `HEAD`, makes
and verifies candidate changes there, and commits accepted changes to a local
branch named `relai/optimizer/{subject}-{timestamp}` in your repository.

This is also why optimization requires a clean tracked tree: candidate
changes are made and evaluated relative to `HEAD`, and there would be no
reliable way to reconcile them with uncommitted local edits. Commit or stash
tracked changes before running it.

To review accepted changes locally:

```sh theme={"system"}
git branch                                        # list optimizer branches
git diff {base-branch}...relai/optimizer/{branch} # inspect the diff
git worktree list                                 # find the branch's worktree
```

The optimizer branch stays checked out in its worktree under
`~/.relai/worktrees`, so `git checkout relai/optimizer/{branch}` in your main
checkout fails with "already checked out". Inspect the files in the worktree
directly, or detach the branch first with
`git worktree remove {worktree-path}` and then check it out normally.

## Pull requests

When [GitHub CLI (`gh`)](https://cli.github.com/) is available and
authenticated, `relai optimize` pushes the optimizer branch and opens a pull
request for accepted changes so they can be reviewed in GitHub.

| Option               | Description                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `--no-pr`            | Keep accepted changes on the local optimizer branch and skip automatic branch push and PR creation. |
| `--pr-base {BRANCH}` | Override the PR base branch. The branch must already exist on `origin`.                             |

With `--no-pr`, accepted changes stay on the local optimizer branch; review
them with the commands above and merge or open a PR yourself.

## Early stopping

| Option         | Default | Description                 |
| -------------- | ------- | --------------------------- |
| `--early-stop` | false   | Enable early-stop behavior. |

## Examples

```sh theme={"system"}
relai optimize
relai optimize --learning-envs {name}
relai optimize --learning-envs {name} --agent-target {target}
relai optimize --tags {tag} --env-file .relai/simulator.env
relai optimize --benchmarks {name} --total-rollouts 50
```

## What to expect

* optimizer progress and rollout results.
* generated or updated optimizer scope at `.relai/optimizer-scope.json`.
* accepted changes committed to a local `relai/optimizer/…` branch.
* optional PR output when [GitHub CLI (`gh`)](https://cli.github.com/) is available and authenticated, unless `--no-pr` is set.

Uploaded optimizer runs appear on the Optimizations tab after you open your agent from the [Agents page](https://platform.relai.ai/agent).

`--total-rollouts` should be set high enough to leave sufficient optimization budget after the 1/3 split. A run needs at least `6 * batch-size` total rollouts to start one optimizer turn. Larger values allow more optimization turns before the reserved final evaluation pass.

<Warning>
  This workflow can write code changes. Review git status, selected environments, credentials, and rollout budget before running it.
</Warning>

Common failures: missing simulator, dirty tracked files, missing runtime credentials, invalid rollout or batch-size limits, backend optimizer failure, or missing [GitHub CLI (`gh`)](https://cli.github.com/) for automatic PR flows.