Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.byterover.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

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

Every setting requires brv restart to take effect. The “restart required” column is omitted below because the answer is always yes in this release.

​
Concurrency

KeyDefaultRangeWhat it controls
agentPool.maxSize101–100How many projects can be active at the same time. One agent process per project.
agentPool.maxConcurrentTasksPerProject51–50Max parallel brv curate / brv query tasks within a single project.

​
LLM

KeyDefaultRangeWhat it controls
llm.iterationBudgetMs600000 (10 min)60000–3600000 (1 min – 1 hour)Wall-clock budget for one agentic loop on a single task.
llm.requestTimeoutMs120000 (2 min)10000–3600000 (10 s – 1 hour)Wall-clock budget for one direct LLM HTTP request. Must satisfy llm.requestTimeoutMs <= llm.iterationBudgetMs.

​
Task history

KeyDefaultRangeWhat it controls
taskHistory.maxEntries100010–10000Per-project cap on the task records the Tasks tab and brv query-log view retain. Older entries roll off automatically.

​
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. 
    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. 
    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:
OSPath
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:
    Profilellm.requestTimeoutMsllm.iterationBudgetMs
    Cloud120000 (2 min)600000 (10 min)
    Local LLM, fast GPU300000 (5 min)1200000 (20 min)
    Local LLM, CPU / heavy quantization900000 (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.

​
--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: 
brv settings set llm.iterationBudgetMs 30m
brv restart

​
Example session

$ 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

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

CLI Reference

Full command-by-command reference for brv.

Daemon-First Architecture

Why agentPool.* settings exist and how the pool reuses processes.

Tasks tab

What taskHistory.maxEntries retains and how it surfaces in the WebUI.

Local Web UI Configuration

Browse and edit the same settings from brv webui.