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

# Settings reference

> Inspect and override the ByteRover CLI's operational settings — concurrency, LLM time budgets, and task-history retention.

`brv` ships with operational defaults that suit most users. The `brv settings` command group lets you inspect those defaults and override them when you need more (or less) headroom.

Changes apply after `brv restart`. The daemon reads `settings.json` once at startup so every agent it spawns runs against the same configuration for the lifetime of the process.

## Subcommands

```bash theme={null}
brv settings                       # List all settings, grouped by category
brv settings list                  # Alias for the bare `brv settings`
brv settings get <key>             # Show current value, default, and range
brv settings set <key> <value>     # Update one key (restart required)
brv settings reset <key>           # Restore one key to its default (restart required)
```

Every subcommand accepts `--format json` for scripting. Validation errors (unknown key, value out of range, wrong unit) exit with code `1` and a message naming the offending key.

## Available keys

<Note>
  Most settings require `brv restart` to take effect — the **Restart** column flags the exceptions. Keys in the **Updates** category take effect on the next `brv` invocation, no restart needed.
</Note>

### Concurrency

| Key                                      | Default | Range     | Restart  | What it controls                                                                 |
| ---------------------------------------- | ------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `agentPool.maxSize`                      | `10`    | `1`–`100` | Required | How many projects can be active at the same time. One agent process per project. |
| `agentPool.maxConcurrentTasksPerProject` | `5`     | `1`–`50`  | Required | Max parallel `brv curate` / `brv query` tasks within a single project.           |

### LLM

| Key                     | Default           | Range                              | Restart  | What it controls                                                                                                 |
| ----------------------- | ----------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `llm.iterationBudgetMs` | `600000` (10 min) | `60000`–`3600000` (1 min – 1 hour) | Required | Wall-clock budget for one agentic loop on a single task.                                                         |
| `llm.requestTimeoutMs`  | `120000` (2 min)  | `10000`–`3600000` (10 s – 1 hour)  | Required | Wall-clock budget for one direct LLM HTTP request. Must satisfy `llm.requestTimeoutMs <= llm.iterationBudgetMs`. |

### Task history

| Key                      | Default | Range        | Restart  | What it controls                                                                                                                                |
| ------------------------ | ------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `taskHistory.maxEntries` | `1000`  | `10`–`10000` | Required | Per-project cap on the task records the [Tasks tab](/local-web-ui/tasks) and `brv query-log view` retain. Older entries roll off automatically. |

### Updates

| Key                      | Default | Values           | Restart      | What it controls                                                                                                                                                                                        |
| ------------------------ | ------- | ---------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update.checkForUpdates` | `true`  | `true` / `false` | Not required | Whether `brv` checks for new versions at startup and runs the background auto-update. Set to `false` to silence the y/n update prompt and stop background auto-update; manual `brv update` still works. |

## Value formats

`brv settings set` parses the value differently depending on the key's unit:

* **Count keys** (e.g. `agentPool.maxSize`, `taskHistory.maxEntries`) — plain integer.

  ```bash theme={null}
  brv settings set agentPool.maxSize 25
  ```

* **Duration keys** (`llm.iterationBudgetMs`, `llm.requestTimeoutMs`) — duration string or raw milliseconds. Accepted suffixes are `ms`, `s`, `m`, `h`; multi-part durations are written with the largest unit first. Whitespace between parts is optional. Fractional values (`1.5h`) are rejected.

  ```bash theme={null}
  brv settings set llm.iterationBudgetMs 30m       # 30 minutes
  brv settings set llm.iterationBudgetMs "1h 30m"  # 90 minutes
  brv settings set llm.iterationBudgetMs 1800000   # raw ms
  ```

## Where settings live

Settings persist in `settings.json` under the global ByteRover data directory:

| OS      | Path                                                                                |
| ------- | ----------------------------------------------------------------------------------- |
| Linux   | `$XDG_DATA_HOME/brv/settings.json` (defaults to `~/.local/share/brv/settings.json`) |
| macOS   | `~/Library/Application Support/brv/settings.json`                                   |
| Windows | `%LOCALAPPDATA%/brv/settings.json`                                                  |

Set the `BRV_DATA_DIR` environment variable to override the directory.

The file is rewritten atomically (temp + rename) on every `brv settings set` / `reset`, so a crash mid-write cannot leave a half-written file. If the daemon encounters a malformed `settings.json` at startup, it logs one warning per problem and falls back to the registered defaults — the bad file is left in place for you to inspect or repair.

## When to change a setting

Most users never need to touch these. The cases worth changing them for:

* **Raise `llm.iterationBudgetMs`** when a single `brv curate` or `brv query` on a slow local LLM (Ollama on CPU, heavy quantization, cold model load) routinely hits the default 10-minute cap on legitimate work. Lower it on cloud providers when you want a stuck task to surface as an error faster.
* **Tune `llm.requestTimeoutMs`** in lockstep with the iteration budget when you change profile. Suggested presets:

  | Profile                             | `llm.requestTimeoutMs` | `llm.iterationBudgetMs` |
  | ----------------------------------- | ---------------------- | ----------------------- |
  | Cloud                               | `120000` (2 min)       | `600000` (10 min)       |
  | Local LLM, fast GPU                 | `300000` (5 min)       | `1200000` (20 min)      |
  | Local LLM, CPU / heavy quantization | `900000` (15 min)      | `3600000` (60 min)      |

  The constraint `llm.requestTimeoutMs <= llm.iterationBudgetMs` is enforced both on `set` and at daemon startup; a file that violates it falls back to defaults for *both* keys.
* **Raise `agentPool.maxSize`** if you actively switch between more than 10 projects in a single daemon session and want them all to keep warm.
* **Lower `taskHistory.maxEntries`** if disk usage from the per-project task journals starts mattering, or raise it if you want deeper history for audit.
* **Set `update.checkForUpdates` to `false`** if you manage `brv` versions on your own schedule (pinned in CI, controlled rollouts, air-gapped environments) and don't want the y/n update prompt at startup. Unlike the other keys, this one takes effect on the next `brv` invocation — no restart needed. See also [Installation & Updates FAQ](/faqs/installation-updates).

## `--timeout` migration

Earlier versions of `brv curate`, `brv query`, and `brv dream` accepted a `--timeout` flag. The flag is still accepted for back-compat but now prints `--timeout is deprecated and has no effect.` to stderr and is ignored.

Use `llm.iterationBudgetMs` instead:

```bash theme={null}
brv settings set llm.iterationBudgetMs 30m
brv restart
```

## Example session

```bash theme={null}
$ brv settings
Settings - scope: global
Run `brv restart` to apply changes.

CONCURRENCY
  agentPool.maxSize                         10       (default 10)         1-100
  agentPool.maxConcurrentTasksPerProject    5        (default 5)          1-50

LLM
  llm.iterationBudgetMs                     10m      (default 10m)        1m-1h
  llm.requestTimeoutMs                      2m       (default 2m)         10s-1h, max loop budget

TASK HISTORY
  taskHistory.maxEntries                    1,000    (default 1,000)      10-10,000

UPDATES
  update.checkForUpdates                    true     (default true)

Set:   brv settings set <key> <value>
Reset: brv settings reset <key>

$ brv settings set agentPool.maxSize 25
Setting saved: agentPool.maxSize = 25. Run `brv restart` to apply.

$ brv settings set update.checkForUpdates false
Setting saved: update.checkForUpdates = false.

$ brv settings get agentPool.maxSize --format json
{"command":"settings get","success":true,"data":{"key":"agentPool.maxSize","current":25,"default":10,"min":1,"max":100,"unit":"count","category":"concurrency","restartRequired":true}}
```

## Next steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="book" href="/reference/cli-reference">
    Full command-by-command reference for `brv`.
  </Card>

  <Card title="Daemon-First Architecture" icon="server" href="/daemon-first-architecture/overview">
    Why `agentPool.*` settings exist and how the pool reuses processes.
  </Card>

  <Card title="Tasks tab" icon="list-checks" href="/local-web-ui/tasks">
    What `taskHistory.maxEntries` retains and how it surfaces in the WebUI.
  </Card>

  <Card title="Local Web UI Configuration" icon="globe" href="/local-web-ui/configuration">
    Browse and edit the same settings from `brv webui`.
  </Card>
</CardGroup>