Overview - Byterover

ByteRover CLI v2.0.0 introduces a daemon-first architecture. The core runtime is now a background daemon process that any client — TUI, CLI commands, MCP server, or the local web UI — can connect to independently. The interactive TUI is no longer required for agents to work; it’s just another client.

Daemon-first architecture requires ByteRover CLI v2.0.0 or later.

Architecture

The daemon (brv-server) runs as a standalone background process. All clients connect to it over Socket.IO:

┌─────────────────────────────────────────────────────────┐
│               Daemon (brv-server)                       │
│                                                         │
│  Socket.IO Transport Server                             │
│  HTTP Server (serves the local web UI)                  │
│  Agent Pool (forked LLM worker processes)               │
│  Task Router                                            │
│  State Server (config, auth, providers)                 │
└──────┬──────────┬──────────────┬────────────────┬───────┘
       │          │              │                │
   TUI Client  CLI Commands  MCP Server       Web UI
   (optional)  brv query     brv mcp          brv webui
               brv curate    (coding agents)
               brv status

The TUI, CLI commands, MCP server, and web UI are all equal clients. None of them own the runtime — the daemon does.

Before vs After

	Before (v1.x)	After (v2.0)
Runtime	LLM loop and task execution lived inside the TUI process	Daemon is a standalone background process
TUI requirement	Agents needed `brv` (the TUI) running to function	TUI is optional — agents connect directly to the daemon
Startup	Had to manually start the TUI first	Any `brv` command auto-starts the daemon on demand
State sharing	Tied to the TUI session	Shared across all clients via the daemon’s state server
Agent processes	Created and destroyed per session	Pooled and reused across commands (no cold starts)

Auto-Start on Demand

Every CLI command auto-spawns the daemon if it’s not already running. No manual setup needed:

# Daemon starts automatically — no need to run `brv` first
brv query "how does auth work?"
# spawns daemon → connects → executes → returns

brv curate "JWT tokens expire in 24h" --files src/auth.ts
# same flow — reuses the already-running daemon

brv status
# same flow

You never need to manage the daemon manually. It starts when you need it and shuts down when you don’t.

Daemon Lifecycle

Spawns on first use

Any brv command auto-starts the daemon if it’s not already running. The daemon spawns as a detached child process, selects a random port from the dynamic range (49152–65535), and writes its metadata to a platform-specific data directory so clients can find it.

Platform	Metadata path
macOS	`~/Library/Application Support/brv/daemon.json`
Linux	`$XDG_DATA_HOME/brv/daemon.json` (defaults to `~/.local/share/brv/daemon.json`)
Windows	`%LOCALAPPDATA%/brv/daemon.json`

Stays alive

The daemon persists across commands. Subsequent calls reuse the same process — no startup overhead after the first command.

Agent pool reuse

Each project gets a dedicated LLM worker process, forked on demand when the first task arrives. Once forked, the agent stays warm and is reused for subsequent tasks on the same project — eliminating cold starts on back-to-back commands. By default, the pool supports up to 10 project agents, each handling up to 5 tasks simultaneously. Both numbers are tunable via brv settings (agentPool.maxSize and agentPool.maxConcurrentTasksPerProject).

Hot-swap providers

Switching LLM providers via /providers or brv providers connect propagates instantly to all running agents through the daemon’s event system. No restart required.

Auto-shutdown

The daemon shuts down automatically after 30 minutes of inactivity. Individual agent processes are cleaned up after 15 minutes of being idle. This keeps your system clean without any manual intervention.

Singleton lock

A global instance lock prevents multiple daemons from running simultaneously. The lock uses an atomic temp-file-and-rename mechanism to avoid race conditions when multiple commands start at the same time.

Headless & CI/CD

All CLI commands support --format json for structured output, making ByteRover fully scriptable:

brv query "what are the API endpoints?" --format json
brv curate "Added rate limiting to /api/v2" --files src/middleware.ts --format json
brv status --format json

The daemon auto-starts in headless environments just as it does interactively — no extra configuration needed. For full details on headless execution, JSON output format, authentication for automation, and CI/CD integration, see the Headless Mode documentation.

Technical Details

Key constants from the daemon runtime:

Parameter	Value
Transport	Socket.IO (WebSocket-only)
Port range	49152–65535 (dynamic)
Heartbeat interval	5 seconds
Server idle timeout	30 minutes
Agent idle timeout	15 minutes
Max agent pool size	10 processes (default; tunable via `agentPool.maxSize`)
Max concurrent tasks per agent	5 (default; tunable via `agentPool.maxConcurrentTasksPerProject`)

Next Steps

Local Web UI

Browser-based client served by the daemon

Headless Mode

Non-interactive execution for CI/CD pipelines and automation

CLI Reference

Complete command reference for all ByteRover CLI commands

Agent Connectors

Connect coding agents like Cursor, Claude Code, and Windsurf

LLM Providers

Connect external LLM providers and bring your own API key

​Architecture

​Before vs After

​Auto-Start on Demand

​Daemon Lifecycle

​Spawns on first use

​Stays alive

​Agent pool reuse

​Hot-swap providers

​Auto-shutdown

​Singleton lock

​Headless & CI/CD

​Technical Details

​Next Steps

Local Web UI

Headless Mode

CLI Reference

Agent Connectors

LLM Providers

Architecture

Before vs After

Auto-Start on Demand

Daemon Lifecycle

Spawns on first use

Stays alive

Agent pool reuse

Hot-swap providers

Auto-shutdown

Singleton lock

Headless & CI/CD

Technical Details

Next Steps