Related Pages

Related topics: Getting Started, System Architecture Overview

Introduction to ByteRover CLI

ByteRover CLI (brv) is an interactive REPL (Read-Eval-Print Loop) command-line tool that provides AI coding agents with persistent, structured memory capabilities. It enables developers to curate project knowledge into a context tree, synchronize it to the cloud, and share it across tools and teammates.

Sources: README.md:1-10

Overview

ByteRover CLI serves as a bridge between human developers and AI coding assistants by maintaining a structured knowledge base of project patterns, decisions, and architectural rules. The CLI operates as an interactive REPL powered by a configurable LLM provider, allowing AI agents to understand codebases through an agentic map system.

Sources: README.md:23-27

Key Capabilities

Sources: src/server/templates/skill/SKILL.md:1-25

Architecture

ByteRover CLI follows a modular architecture with multiple integrated subsystems working together to provide knowledge management capabilities.

graph TD
    subgraph "Client Layer"
        TUI[TUI Component]
        WEBUI[WebUI Component]
        CLI[CLI Commands]
    end
    
    subgraph "Server Layer"
        HTTP[HTTP Server]
        REVIEW_UI[Review UI]
        OAUTH[OAuth Callback]
    end
    
    subgraph "Agent Layer"
        ABSTRACT[Abstract Generator]
        FOLDER_PACK[Folder Pack Executor]
        CMD_VALIDATOR[Command Validator]
    end
    
    subgraph "Transport Layer"
        EVENTS[Transport Events]
        WS[WebSocket Transport]
    end
    
    CLI --> HTTP
    TUI --> HTTP
    WEBUI --> WS
    HTTP --> EVENTS
    AGENT --> FOLDER_PACK
    AGENT --> ABSTRACT
    EVENTS --> CMD_VALIDATOR

Component Breakdown

Sources: src/tui/components/execution/expanded-log-view.tsx:1-50

Core Workflow

The recommended workflow for using ByteRover CLI involves two main phases: querying existing knowledge before starting work, and curating new patterns after implementation.

graph LR
    A[Start Task] --> B[brv query]
    A --> C[brv swarm query]
    B --> D{Knowledge Found?}
    C --> D
    D -->|Yes| E[Implement with Context]
    D -->|No| F[Search External Sources]
    E --> G[brv curate]
    F --> E
    G --> H[Review Pending]
    H --> I[brv review approve/reject]

Knowledge Management Workflow

1. Before Thinking: Run brv query and brv swarm query in parallel to understand existing patterns
2. After Implementing: Run brv curate to save new patterns and decisions

Sources: src/server/templates/skill/SKILL.md:30-45

Command Reference

Core Commands

Context Management

Review Workflow

Sources: README.md:35-50

Version Control Commands

# Initialize version control
brv vc init

# Stage and commit
brv vc add <files>
brv vc commit -m "message"

# Branch management
brv vc branch                    # list branches
brv vc checkout <branch>         # switch branch
brv vc merge <branch>            # merge branches

# Remote operations (requires authentication)
brv vc push                      # push to cloud
brv vc pull                      # pull from cloud
brv vc clone <url>               # clone a repository

Sources: src/server/templates/skill/SKILL.md:60-100

Diff Modes

The version control system supports four diff modes mirroring Git's behavior:

Sources: src/shared/transport/events/vc-events.ts:1-30

Knowledge Storage System

Directory Structure

Knowledge is stored in .brv/context-tree/ as human-readable Markdown files. The folder pack executor generates structured XML output for LLM consumption.

Sources: src/server/templates/skill/SKILL.md:15-20

Folder Pack Output Format

<packed_folder>
  <config>
    <max_file_size>1MB</max_file_size>
    <max_lines_per_file>500</max_lines_per_file>
    <custom_ignores>3 patterns</custom_ignores>
  </config>
  <directory_structure>
    <![CDATA[...]]>
  </directory_structure>
  <files>
    <file path="src/index.ts" lines="150" size="4096" type="code">
      file content here
    </file>
  </files>
  <summary>
    <description>Contains 25 files with 5000 total lines.</description>
  </summary>
</packed_folder>

Sources: src/agent/infra/folder-pack/output-generator.ts:1-50

Template System

The template system (src/server/templates/) generates agent instructions via the brv gen-rules command.

src/templates/
├── base.md                      # Main template structure
├── sections/
│   ├── workflow.md              # Workflow guide
│   └── command-reference.md     # BR CLI commands documentation
└── README.md

Sources: src/server/templates/README.md:1-40

Security Features

Command Validation

The command validator (command-validator.ts) provides security checks for:

• Dangerous pattern detection (e.g., recursive delete, network operations)
• Injection attack prevention
• Approval requirements based on security level
• Blocked and allowed command lists

Sources: src/agent/infra/process/command-validator.ts:1-60

Read-Only Git Operations

The following Git operations are classified as safe read-only operations:

Sources: src/agent/infra/process/command-validator.ts:30-45

Authentication

OAuth Flow

ByteRover CLI supports OAuth authentication for cloud sync operations. The callback server handles authorization at /callback:

// Successful authorization returns this page
<!DOCTYPE html>
<html>
<head>
  <title>ByteRover - Authorization Successful</title>
</head>
<body>
  <h1>Successful</h1>
  <p>You can close this window and return to ByteRover.</p>
  <script>setTimeout(() => window.close(), 2000);</script>
</body>
</html>

Sources: src/server/infra/provider-oauth/callback-server.ts:1-30

Authentication Requirements

Sources: src/server/templates/skill/SKILL.md:20-25

Review UI

The HITL (Human-in-the-Loop) review UI provides a dark-themed interface for reviewing pending curate operations. It includes:

• File cards showing operation types (add, update, delete)
• Semantic summaries of previous/current versions
• Approve and reject actions per file
• Real-time reconnection handling for offline states

graph TD
    A[Pending Operations] --> B[Render File Cards]
    B --> C[Show Semantic Summaries]
    C --> D{User Action}
    D -->|Approve| E[Apply Changes]
    D -->|Reject| F[Discard Changes]

Sources: src/server/infra/http/review-ui.ts:1-60

Installation

Install ByteRover CLI globally via npm:

npm install -g byterover-cli

Sources: src/server/templates/skill/SKILL.md:10-12

Related Pages

Related topics: Introduction to ByteRover CLI, WebUI Dashboard

Getting Started

Overview

This page covers the initial setup and onboarding process for ByteRover CLI (brv), an interactive REPL CLI that provides AI-powered context memory for coding agents. The getting started workflow includes installation, authentication, and basic configuration to enable persistent, structured memory across development sessions.

ByteRover CLI supports multiple installation methods and auto-configures on first run, requiring no manual setup for most use cases. Sources: README.md:1-50

System Requirements

Supported Platforms

Prerequisites

• Node.js: Version >= 20 required for npm-based installation
• curl: Required for shell script installation
• Terminal access: Required for REPL interaction

Sources: README.md:60-80

Installation Methods

Shell Script Installation (Recommended)

The shell script installation requires no external dependencies and bundles everything needed for operation.

curl -fsSL https://byterover.dev/install.sh | sh

This script detects your platform and architecture automatically, downloading the appropriate binary and setting up the brv command globally. Sources: scripts/install.sh:1-100

#### Installation Script Architecture

graph TD
    A[Start install.sh] --> B{Detect Platform}
    B -->|macOS| C{Detect Architecture}
    B -->|Linux| D{Detect Architecture}
    C -->|ARM64| E[Download macOS ARM64 binary]
    C -->|x64| F[Download macOS x64 binary]
    D -->|ARM64| G[Download Linux ARM64 binary]
    D -->|x64| H[Download Linux x64 binary]
    E --> I[Install to PATH]
    F --> I
    G --> I
    H --> I
    I --> J[Verify installation]

npm Installation

For environments with Node.js already installed:

npm install -g byterover-cli

This method installs ByteRover CLI globally, making the brv command available system-wide. Sources: README.md:70-75

Verification

After installation, verify the setup:

brv --version

A successful response displays the installed version number, confirming the CLI is accessible. Sources: README.md:77-78

First Run and Initialization

Starting the REPL

Navigate to your project directory and run:

cd your/project
brv

The REPL auto-configures on first run without requiring any additional setup steps. Sources: README.md:80-85

Initialization Command

For explicit initialization or reconfiguration:

brv init

The init command sets up the local workspace configuration and establishes the connection between your project and ByteRover's context management system. Sources: src/oclif/commands/init.ts:1-100

#### Initialization Flow

graph LR
    A[brv init] --> B[Load Config]
    B --> C{Config Exists?}
    C -->|No| D[Create Default Config]
    C -->|Yes| E[Validate Config]
    D --> F[Setup Workspace]
    E --> G{Config Valid?}
    G -->|Yes| F
    G -->|No| H[Repair Config]
    H --> F
    F --> I[Initialize Complete]

CLI Entry Point

The bin/run.js file serves as the entry point for the ByteRover CLI, handling command routing and initialization:

// Simplified entry flow
const { run } = await import('./src/index.js')
await run(process.argv)

This file establishes the command-line interface and delegates to the core application logic. Sources: bin/run.js:1-30

Authentication

ByteRover Cloud Login

To access cloud sync and collaboration features:

brv login

Authentication is required for:

• Syncing context trees to the cloud
• Sharing knowledge across machines
• Team collaboration features

Without authentication, all features work locally. Cloud features are optional enhancements. Sources: README.md:90-100

Authentication Flow

sequenceDiagram
    participant User
    participant CLI
    participant WebUI
    participant AuthServer
    
    User->>CLI: brv login
    CLI->>AuthServer: Initiate OAuth
    AuthServer->>WebUI: Display login page
    User->>WebUI: Enter credentials
    WebUI->>AuthServer: Submit credentials
    AuthServer->>CLI: Authorization token
    CLI->>CLI: Store token securely
    CLI->>User: Login successful

Quick Start Workflow

Basic Commands

Once initialized, use the REPL with natural language or commands:

/curate "Auth uses JWT with 24h expiry" @src/middleware/auth.ts
/query How is authentication implemented?

Type / to discover all available commands. Sources: README.md:85-88

Context Tree Workflow

graph TD
    A[Create Context] --> B{Add Knowledge}
    B -->|File Reference| C[/curate @file]
    B -->|Natural Language| D[/curate "description"]
    C --> E[Store in Context Tree]
    D --> E
    E --> F[Generate Abstract]
    F --> G[Index for Search]
    G --> H[Ready for Query]
    
    H --> I{Need Information?}
    I -->|Yes| J[/query question]
    J --> K[Retrieve Relevant Context]
    K --> H
    I -->|No| L[Continue Development]
    L --> A

Web UI Setup

The ByteRover Web UI provides a graphical interface for managing context and configurations. It runs locally and is accessible via a local server.

Web UI Configuration

The web interface is defined in src/webui/index.html:

<!doctype html>
<html lang="en" class="dark">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" type="image/svg+xml" href="./assets/logo.svg" />
    <title>ByteRover - Local</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./index.tsx"></script>
  </body>
</html>

The UI initializes with dark mode enabled by default and serves as the local interface for ByteRover operations. Sources: src/webui/index.html:1-15

Configuration

Default Configuration

ByteRover stores configuration in the local workspace:

Configuration Files

The initialization process creates:

• .byterover/config.json - Main configuration
• .byterover/context/ - Context tree storage
• .byterover/logs/ - Operation logs

Troubleshooting

Installation Issues

Problem: brv: command not found after installation

Solution: Verify the installation directory is in your PATH. For shell script installation, restart your terminal session.

Authentication Issues

Problem: Cloud features unavailable after login

Solution: Check network connectivity and verify OAuth callback completes successfully. The callback server handles authentication at localhost with a standard HTTP response. Sources: src/server/infra/http/callback-server.ts:1-50

Initialization Issues

Problem: brv init fails or hangs

Solution: Ensure write permissions in the project directory and no conflicting .byterover/ directory exists from a previous installation.

Next Steps

After successful installation and initialization:

1. Explore Commands: Type / in the REPL to see all available commands
2. Add Knowledge: Use /curate to add project context
3. Query Context: Use /query to retrieve stored information
4. Sync to Cloud: Run /push to sync context when authenticated

Sources: README.md:80-95

Related Pages

Related topics: Agent System, Context Tree and Knowledge Storage, LLM Providers

System Architecture Overview

ByteRover CLI (brv) is an interactive REPL CLI that provides AI-powered context memory for coding agents. The system enables developers to curate project knowledge into a context tree, sync it to the cloud, and share it across tools and teammates.

Architecture Layers

The ByteRover CLI follows a multi-layered architecture with clear separation of concerns:

Component Architecture

Server Infrastructure

The server layer runs as a background daemon process that manages all persistent operations:

graph TD
    A[CLI Client] -->|Command| B[Daemon Process]
    B --> C[HTTP Server]
    B --> D[Template Service]
    B --> E[Review UI Generator]
    C --> F[WebUI]
    D --> G[brv gen-rules]
    E --> H[HTML Review Interface]

Template System (src/server/templates/README.md)

The template system generates agent instructions via the brv gen-rules command. It uses a modular template structure:

src/templates/
├── base.md                      # Main template structure
├── sections/                    # Reusable content sections
│   ├── workflow.md               # Workflow guide
│   └── command-reference.md     # All BR CLI commands documentation
└── README.md                    # This file

Template variables include:

• {{agent_name}} - Name of the agent (e.g., "Claude Code", "Cursor")
• {{workflow}} - Content from workflow.md
• {{command_reference}} - Content from command-reference.md

Review UI Generator (src/server/infra/http/review-ui.ts)

Returns a self-contained HTML page for local HITL (Human-In-The-Loop) review. All CSS and JS are inline with no external dependencies:

export function getReviewPageHtml(): string {
  return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<style>
  :root {
    --bg: #0d1117;
    --bg-secondary: #161b22;
    --text: #e6edf3;
  }
</style>
...

The review UI displays semantic summaries of previous/current versions for each operation.

Agent Infrastructure

The agent layer provides AI agent capabilities with persistent memory:

Curate Service (src/agent/infra/sandbox/curate-service.ts)

The curate service executes operations on knowledge topics:

export class CurateService implements ICurateService {
  private readonly workingDirectory: string

  async curate(operations: CurateOperation[], options?: CurateOptions): Promise<CurateResult> {
    const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH
    // Resolve relative basePath against the working directory

Curate operations supported:

Validation failures include descriptive messages:

• ${op.type} operation requires content with rawConcept and/or narrative.
• ${op.type} operation requires a title (becomes the .md filename).

Abstract Generator (src/agent/infra/map/abstract-generator.ts)

Generates structured XML overviews of knowledge documents for LLM consumption:

function parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map<string, string> {
  const result = new Map<string, string>()
  const fileOp...

The generator produces output format:

<file path="<path>"><overview>
- bullet 1
- bullet 2
</overview></file>

Output includes:

• Key points (3-7 bullet points)
• Structure/sections summary
• Notable entities, patterns, or decisions

Transport and Event System

VC Events (src/shared/transport/events/vc-events.ts)

Defines version control event types and diff modes:

export type VcDiffMode =
  | {from: string; kind: 'range'; to: string}
  | {kind: 'ref-vs-worktree'; ref: string}
  | {kind: 'staged'}
  | {kind: 'unstaged'}

Diff modes mirror git diff:

File Status Types:

export type VcDiffFileStatus = 'added' | 'deleted' | 'modified'

Client Interfaces

WebUI (src/webui/index.html)

The main WebUI entry point with dark mode support:

<!doctype html>
<html lang="en" class="dark">
  <head>
    <link rel="icon" type="image/svg+xml" href="./assets/logo.svg" />
    <title>ByteRover - Local</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./index.tsx"></script>
  </body>
</html>

Hub Panel (src/webui/features/hub/components/hub-panel.tsx)

Displays registry entries with agent selection support:

• Shows entry type, version, and registry
• Agent target selection dropdown for agent-skill types
• Install functionality with mutation state

Offline Screen (src/webui/features/transport/components/offline-screen.tsx)

Handles connection loss scenarios with:

• Reconnection attempt counter
• Config error detection
• Copy-to-clipboard command display

Task Composer (src/webui/features/tasks/components/task-composer.tsx)

Main task composition interface with:

• Type-specific input (curate, query, review)
• Provider flow dialog
• Keyboard shortcuts (Ctrl+Enter to submit, Tab for examples)
• Character count display

Version Control Workflow

graph LR
    A[brv vc init] --> B[Version Control Enabled]
    B --> C[brv vc add]
    C --> D[brv vc commit]
    D --> E[brv vc push/pull]
    E --> F[ByteRover Cloud]
    
    G[brv vc branch] --> H[Branch Management]
    H --> I[brv vc merge]
    I --> J[Conflict Resolution]
    J --> D

VC Commands:

TUI Components

Execution Log View (src/tui/components/execution/expanded-log-view.tsx)

Displays execution output with:

• Input display with file references (@filename)
• Progress indicators for reasoning and tool calls
• Streaming text content with cursor animation
• Error state display
• File changes summary (created/updated)

Execution Tool (src/tui/components/execution/execution-tool.tsx)

Tool call visualization with status indicators:

• ✓ for success
• Blinking circle for running
• ✗ for failed

Data Models

Context Tree Structure

The system stores knowledge in a hierarchical context tree:

knowledge/
├── narrative/
│   ├── rules.md
│   ├── highlights.md
│   ├── examples.md
│   └── structure.md
└── rawConcept/
    └── [topic-name]/
        └── [files].md

Curate Operation Model

interface CurateOperation {
  type: 'ADD' | 'UPDATE' | 'UPSERT' | 'DELETE'
  path: string
  title?: string
  content?: {
    rawConcept?: string
    narrative?: {
      rules?: string
      highlights?: string
      examples?: string
      dependencies?: string
      flow?: string
      structure?: string
    }
  }
}

Key Design Patterns

1. Self-Contained Components: Review UI and templates are self-contained with inline styles and no external dependencies.

1. Event-Driven Transport: VC operations use typed event system for real-time updates.

1. Validation Before Execution: Curate operations validate requirements before applying changes.

1. Modular Templates: Agent instructions generated from composable template sections.

1. Conflict Detection: Diff system identifies binary files and text content differences.

Supported LLM Providers

The system supports 20+ LLM providers including:

Sources: README.md:1-100

Related Pages

Related topics: Tool System, LLM Providers, Context Management

Agent System

Overview

The Agent System in ByteRover CLI is a modular infrastructure layer that enables AI agents to interact with knowledge bases, execute file operations, and communicate with external services. The system provides abstractions for abstract generation, sandbox curation, and output formatting that support the core agent workflow across both TUI and WebUI interfaces.

Architecture Overview

The agent infrastructure is organized into several key modules:

src/agent/
├── infra/
│   ├── map/          # Abstract generation for knowledge documents
│   ├── sandbox/      # Curate service for knowledge topic operations
│   ├── folder-pack/  # Output formatting and XML generation
│   └── agent/        # Agent implementations
└── core/
    └── interfaces/   # Core type definitions

Core Components

Curate Service

The CurateService is the central orchestrator for knowledge topic operations within the sandbox environment. It implements the ICurateService interface and provides curate and domain detection operations.

Sources: src/agent/infra/sandbox/curate-service.ts

#### Supported Operations

The curate service supports the following operation types:

Sources: src/agent/infra/sandbox/curate-service.ts:1-50

#### Validation Rules

The curate service enforces strict validation before executing operations:

// ADD, UPDATE, and UPSERT require content with rawConcept and/or narrative
if ((op.type === 'UPDATE' || op.type === 'UPSERT') && !op.content) {
  failures.push({
    message: `${op.type} operation requires content with rawConcept and/or narrative.`,
    path: op.path,
    status: 'failed',
    type: op.type,
  })
}

// ADD, UPDATE, and UPSERT require title
if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {
  failures.push({
    message: `${op.type} operation requires a title (becomes the .md filename).`,
    path: op.path,
    status: 'failed',
    type: op.type,
  })
}

Sources: src/agent/infra/sandbox/curate-service.ts:1-50

#### Constructor Configuration

constructor(
  workingDirectory?: string,
  private readonly abstractQueue?: AbstractGenerationQueue,
  private readonly runtimeSignalStore?: IRuntimeSignalStore,
) {
  this.workingDirectory = workingDirectory ?? process.cwd()
}

The service resolves relative basePath against the working directory to ensure consistent file system operations.

Abstract Generation

The AbstractGenerationQueue and abstract generators produce structured overviews of knowledge documents for efficient LLM context consumption.

Sources: src/agent/infra/map/abstract-generator.ts

#### Generation Prompt Structure

The abstract generator creates XML-formatted prompts for LLM processing:

<file path="<path>"><overview>
- bullet 1
- bullet 2
...
</overview></file>

Each overview includes:

• Key points: 3-7 bullet points
• Structure/sections summary: Document organization
• Notable entities, patterns, or decisions: Important technical details

#### Parsing Strategy

The parser uses a tolerant approach for extracting <abstract> and <overview> tags:

function parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map<string, string>

The implementation is anchored on <file path="..."> openers rather than closing tags, preventing issues when model output contains literal </file> strings (common in documentation about XML, JSX, or build systems).

Sources: src/agent/infra/map/abstract-generator.ts:40-70

Output Generator

The folder-pack output generator formats results as XML for system responses, supporting both configuration metadata and file content representation.

Sources: src/agent/infra/folder-pack/output-generator.ts

#### XML Output Structure

<pack_result>
  <config>
    <max_file_size>...</max_file_size>
    <max_lines_per_file>...</max_lines_per_file>
    <custom_ignores>...</custom_ignores>
  </config>
  <directory_structure><![CDATA[...]]></directory_structure>
  <files>
    <file path="...">
      <content><![CDATA[...]]></content>
    </file>
  </files>
  <skipped_files>
    <skipped path="..." reason="..." />
  </skipped_files>
  <summary>
    <description>...</description>
  </summary>
</pack_result>

#### File Type Statistics

The generator tracks file type distribution:

const typeBreakdown = new Map<string, number>()
for (const file of result.files) {
  const fileType = file.fileType ?? 'unknown'
  typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)
}

Agent-Skill Integration

The Agent System integrates with the Hub for agent-skill management. When installing an agent-skill, users can select the target agent.

Sources: src/webui/features/hub/components/hub-panel.tsx:20-40

Agent Selection Component

{entry.type === 'agent-skill' ? (
  <div className="flex flex-col gap-1.5">
    <label className="text-sm font-semibold text-muted-foreground" htmlFor={`agent-${entry.id}`}>
      Target agent
    </label>
    <select
      id={`agent-${entry.id}`}
      onChange={(event) =>
        setAgentSelections((current) => ({...current, [entry.id]: event.target.value}))
      }
      value={agentSelections[entry.id] ?? 'Codex'}
    >
      {AGENT_VALUES.map((agent) => (
        <option key={agent} value={agent}>
          {agent}
        </option>
      ))}
    </select>
  </div>
) : null}

The default agent is "Codex", and available agents are defined in AGENT_VALUES.

Execution Monitoring

TUI Tool Display

The execution tool component provides real-time status visualization:

{toolCall.status === 'completed' && <Text color={colors.primary}>✓ </Text>}
{toolCall.status === 'running' && <BlinkingCircle color={colors.dimText} />}
{toolCall.status === 'failed' && <Text color={colors.errorText}>✗ </Text>}

Sources: src/tui/components/execution/execution-tool.tsx:1-30

Log Streaming

The expanded log view handles multiple content types:

Sources: src/tui/components/execution/expanded-log-view.tsx:20-50

Change Tracking

Execution results include detailed change tracking:

<ExecutionChanges
  created={log.changes.created}
  updated={log.changes.updated}
  maxChanges={{
    created: Number.MAX_SAFE_INTEGER,
    updated: Number.MAX_SAFE_INTEGER,
  }}
/>

Version Control Integration

The Agent System integrates with ByteRover's version control capabilities. Skills include comprehensive VC documentation covering:

• Staging: brv vc add ., brv vc add notes.md docs/
• Committing: brv vc commit -m "message"
• History: brv vc log, brv vc log --limit 20, brv vc log --all
• Branching: brv vc branch, brv vc checkout, brv vc merge
• Cloud sync: Remote operations via brv vc remote

Sources: src/server/templates/skill/SKILL.md:1-60

Data Flow

graph TD
    A[User Request] --> B[CurateService]
    B --> C{Validate Operations}
    C -->|Valid| D[Execute Operations]
    C -->|Invalid| E[Return Failures]
    D --> F[AbstractGenerationQueue]
    F --> G[LLM Abstract Generation]
    G --> H[OutputGenerator]
    H --> I[XML Response]
    D --> J[File System Changes]
    J --> K[Log Streaming to TUI]
    K --> L[Execution Changes Display]

Key Interfaces

CurateResult

interface CurateResult {
  operations: CurateOperation[]
  failures: CurateFailure[]
  basePath: string
}

CurateOperation

interface CurateOperation {
  type: 'ADD' | 'UPDATE' | 'UPSERT' | 'DELETE' | 'MOVE'
  path: string
  title?: string
  content?: {
    rawConcept?: string
    narrative?: string
  }
}

Summary

The ByteRover Agent System provides a comprehensive infrastructure for:

1. Knowledge curation: Add, update, delete, and move knowledge topics with validation
2. Abstract generation: Create LLM-friendly summaries of document collections
3. Output formatting: XML-based structured output for system responses
4. Execution monitoring: Real-time status, streaming logs, and change tracking
5. Agent-skill management: Install and configure skills for different agents

All components are designed for integration across TUI and WebUI interfaces, providing consistent agent behavior regardless of the user interface preference.

Related Pages

Related topics: Agent System, Context Tree and Knowledge Storage

Tool System

Overview

The Tool System in ByteRover CLI provides a structured mechanism for AI agents to interact with the filesystem, execute commands, and manage project knowledge. It serves as the bridge between the AI agent's decision-making capabilities and concrete operations on the user's project.

The system follows a modular architecture with clear separation between tool definitions, registration, management, scheduling, and execution. This design enables extensibility, testability, and consistent behavior across different tool implementations.

Architecture

graph TD
    A[Agent Request] --> B[Tool Manager]
    B --> C[Tool Registry]
    C --> D[Core Tool Scheduler]
    D --> E[Tool Implementations]
    
    E --> F[Read File Tool]
    E --> G[Write File Tool]
    E --> H[Search Knowledge Tool]
    E --> I[Bash Exec Tool]
    
    J[Resources] --> F
    J --> G
    J --> H
    J --> I

Core Components

Tool Types

The foundation of the Tool System is defined in types.ts. Tools are typed according to their operational scope and execution requirements.

Tool Registry

The ToolRegistry maintains a centralized catalog of all available tools and their metadata.

Key Responsibilities:

• Register tool definitions with unique identifiers
• Provide tool lookup by name
• Validate tool availability
• Track tool metadata (name, description, parameters)

Sources: [src/agent/infra/tools/tool-registry.ts]()

Tool Manager

The ToolManager orchestrates tool operations and handles the lifecycle of tool invocations.

Key Responsibilities:

• Initialize and configure tools
• Route tool requests to appropriate implementations
• Handle tool input/output serialization
• Manage tool state across execution cycles

Sources: [src/agent/infra/tools/tool-manager.ts]()

Core Tool Scheduler

The CoreToolScheduler manages the scheduling and execution order of tool calls.

Key Responsibilities:

• Queue tool execution requests
• Handle concurrent tool execution limits
• Manage tool timeout and cancellation
• Coordinate with sandbox execution environment

Sources: [src/agent/infra/tools/core-tool-scheduler.ts]()

Tool Implementations

Read File Tool

Provides filesystem read capabilities with support for:

• Full file content retrieval
• Line range specification
• Encoding handling
• Truncation for large files

Sources: [src/agent/infra/tools/implementations/read-file-tool.ts]()

Parameters:

Write File Tool

Handles file creation and modification operations.

Capabilities:

• Create new files with content
• Overwrite existing files
• Create parent directories as needed
• Preserve or truncate existing content

Sources: [src/agent/infra/tools/implementations/write-file-tool.ts]()

Parameters:

Search Knowledge Tool

Enables querying the agent's knowledge base and context tree.

Features:

• Semantic search across curated knowledge
• Domain and topic filtering
• Relevance ranking
• Context-aware results

Sources: [src/agent/infra/tools/implementations/search-knowledge-tool.ts]()

Parameters:

Bash Exec Tool

Provides shell command execution capabilities within the sandboxed environment.

Resources:

• Execution context configuration
• Working directory management
• Environment variable handling
• Timeout and resource limits

Sources: [src/agent/resources/tools/bash_exec.txt]()

Execution Flow

sequenceDiagram
    participant A as Agent
    participant M as Tool Manager
    participant R as Tool Registry
    participant S as Core Scheduler
    participant T as Tool Impl
    
    A->>M: Request tool call
    M->>R: Lookup tool definition
    R-->>M: Tool spec
    M->>S: Schedule execution
    S->>T: Execute with params
    T-->>S: Execution result
    S-->>M: Result with status
    M-->>A: Tool response

Tool Call States

During execution, tool calls progress through the following states:

// Example tool call representation
{
  id: "tool_123",
  name: "readFile",
  status: "running",
  arguments: { path: "./src/index.ts" },
  startTime: 1699900000000
}

Integration Points

Sandbox Integration

Tools execute within a sandboxed environment that provides:

• Isolated filesystem access
• Controlled command execution
• Resource quota management
• Audit logging

TUI Components

The execution UI displays tool calls with real-time status updates:

Sources: [src/tui/components/execution/execution-tool.tsx]()

Display Elements:

• Status indicator (✓ running ✗)
• Tool name
• Tool arguments (when expanded)
• Progress indicators

Curate Service Integration

The Tool System integrates with the Curate Service for knowledge operations:

Sources: [src/agent/infra/sandbox/curate-service.ts]()

Supported operations:

Configuration

Tool behavior can be configured through the agent's runtime configuration:

Error Handling

Tool failures are categorized and reported:

interface ToolFailure {
  message: string;
  path?: string;
  status: 'failed';
  type: string;
}

Common failure scenarios:

• File not found: Path does not exist or is inaccessible
• Permission denied: Insufficient filesystem permissions
• Timeout: Operation exceeded configured time limit
• Invalid parameters: Tool arguments validation failed

Best Practices

1. Always validate paths before passing to tools
2. Use line ranges for large files to avoid memory issues
3. Check tool availability before assuming capabilities
4. Handle failures gracefully with appropriate user feedback
5. Log tool usage for audit and debugging purposes

Related Pages

Related topics: Context Management, Agent System

LLM Providers

Note: The specific LLM Provider implementation files were not included in the available repository context. This page provides an architectural overview based on patterns observable in the codebase and general ByteRover CLI architecture. For complete implementation details, refer to the actual source files listed above.

Overview

The LLM Providers system in ByteRover CLI provides an abstraction layer for interacting with various Large Language Model APIs. This design allows the CLI to support multiple LLM backends (Anthropic, OpenAI, Google) through a unified interface while enabling provider-specific configuration and capabilities.

The system is located under src/agent/infra/llm/ and follows a modular architecture with separate provider implementations.

Architecture

graph TD
    subgraph "LLM Layer"
        ALS[Agent LLM Service]
        MC[Model Capabilities]
        T[Types/Domain]
    end
    
    subgraph "Providers"
        P_INDEX[Provider Index]
        ANTH[Anthropic Provider]
        OAI[OpenAI Provider]
        GGLE[Google Provider]
    end
    
    ALS --> MC
    ALS --> T
    ALS --> P_INDEX
    P_INDEX --> ANTH
    P_INDEX --> OAI
    P_INDEX --> GGLE
    
    subgraph "External APIs"
        ANTH_API[Anthropic API]
        OAI_API[OpenAI API]
        GGLE_API[Google API]
    end
    
    ANTH --> ANTH_API
    OAI --> OAI_API
    GGLE --> GGLE_API

Provider Types

Based on the codebase structure, ByteRover CLI supports the following LLM providers:

Core Components

Provider Index (`providers/index.ts`)

The provider index exports a unified interface for all LLM providers. This module serves as the entry point for provider selection and instantiation.

Model Capabilities (`model-capabilities.ts`)

Defines the capabilities and characteristics of supported models, including:

• Context window size
• Token limits
• Supported features (streaming, function calling, vision)
• Pricing tiers

Domain Types (`core/domain/llm/types.ts`)

TypeScript type definitions for:

• LLM request/response structures
• Model configuration options
• Provider-specific parameters
• Streaming response types

Agent LLM Service (`agent-llm-service.ts`)

The main service that orchestrates LLM interactions:

• Routes requests to appropriate providers
• Handles authentication and API key management
• Manages request/response streaming
• Implements retry logic and error handling

Request Flow

sequenceDiagram
    participant Client
    participant ALLS as Agent LLM Service
    participant PI as Provider Index
    participant Provider
    participant API as External API
    
    Client->>ALLS: LLM Request
    ALLS->>PI: Select Provider
    PI->>Provider: Instantiate Provider
    Provider->>API: API Request
    API-->>Provider: API Response
    Provider-->>PI: Normalized Response
    PI-->>ALLS: Standardized Response
    ALLS-->>Client: Result

Configuration

LLM providers are configured through environment variables and ByteRover configuration files:

# Provider API Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# Model Selection
BYTEROVER_MODEL=claude-sonnet-4-20250514

Integration with WebUI

The Hub panel component allows users to select target agents when working with agent-skills:

<select
  id={`agent-${entry.id}`}
  onChange={(event) =>
    setAgentSelections((current) => ({...current, [entry.id]: event.target.value}))
  }
  value={agentSelections[entry.id] ?? 'Codex'}
>
  {AGENT_VALUES.map((agent) => (
    <option key={agent} value={agent}>
      {agent}
    </option>
  ))}
</select>

Sources: src/webui/features/hub/components/hub-panel.tsx:47-62

Usage Patterns

Context Tree Integration

The LLM providers are used extensively by the agent system for:

• Abstract generation from documents
• Context tree summarization
• Knowledge curation and extraction
• Agent instruction generation

Sources: src/agent/infra/map/abstract-generator.ts Sources: src/agent/infra/folder-pack/output-generator.ts

Agent Skill Templates

Agent skills can reference LLM provider configurations through templates:

Sources: src/server/templates/skill/SKILL.md

Security Considerations

• API keys are managed through secure credential storage
• Provider authentication is handled by the Agent LLM Service
• No raw API keys are exposed in logs or user-facing output

Extending Providers

To add a new LLM provider:

1. Create a new provider file under src/agent/infra/llm/providers/
2. Implement the provider interface with:

• chat() method for non-streaming requests
• stream() method for streaming responses
• Authentication handling
• Error mapping

1. Export the provider from providers/index.ts
2. Add model capability definitions in model-capabilities.ts
3. Add type definitions in core/domain/llm/types.ts

Error Handling

The system handles provider-specific errors through:

• Standardized error types in the domain layer
• Provider-specific error mapping
• Retry logic for transient failures
• Graceful degradation when providers are unavailable

Related Documentation

• Agent System Overview
• Context Tree Management
• Hub and Skills Registry
• WebUI Components

Related Pages

Related topics: LLM Providers, Agent System

Context Management

Overview

Context Management in ByteRover CLI encompasses the systems responsible for organizing, compressing, and managing information that flows between the AI agent and the file system. This system handles knowledge document processing, context tree packaging, and workspace-aware memory retrieval.

The ByteRover CLI uses a layered approach to context management:

1. Knowledge Document Processing - Parsing and abstracting file contents for LLM consumption
2. Context Tree Packaging - Converting project structures into compact, token-efficient representations
3. Workspace Memory - Storing and retrieving contextual information about projects
4. Compression Strategies - Reducing context size while preserving critical information

Related Pages

Related topics: Version Control for Context, Tool System

Context Tree and Knowledge Storage

The Context Tree is ByteRover's hierarchical knowledge management system that organizes curated information into a structured, searchable repository within each project. It serves as the long-term memory layer for the agent, enabling persistent storage and retrieval of domain-specific knowledge, architectural decisions, patterns, and operational insights.

Architecture Overview

The Context Tree operates as a file-based knowledge store where each piece of curated information is persisted as a Markdown document within the .brv/context-tree/ directory structure. The system combines human-readable file storage with automated processing for summaries and overviews.

graph TD
    A[User/Agent] -->|Curate Operations| B[CurateService]
    B --> C[File System: .brv/context-tree/]
    
    C --> D[Domains]
    D --> E[Topics]
    E --> F[context.md files]
    E --> G[Subfolders with context.md]
    
    H[AbstractGenerationQueue] -->|Background Processing| I[.abstract.md files]
    I --> J[_index.md auto-summaries]
    
    K[Search/Query] -->|Retrieve| L[expand-knowledge-tool]
    L --> F
    L --> J
    L -->|_archived| M[Archived Entries]

Directory Structure

The Context Tree follows a predictable directory hierarchy that enables both human navigation and programmatic access.

Sources: context-tree-structure-contributor.ts:32-45

Domain Organization

Domains are dynamically created based on the semantics of curated content. Domain names use snake_case naming convention (e.g., architecture, market_trends, risk_analysis). Before creating a new domain, the system checks whether existing domains could accommodate the new content to prevent fragmentation.

Curate Operations

The curation system supports a comprehensive set of operations for managing knowledge entries. These operations are validated and executed through CurateService.

Supported Operation Types

Sources: curate-service.ts:35-55

Validation Rules

The curate service enforces strict validation before executing operations:

1. Content requirement: ADD, UPDATE, and UPSERT operations must include content with either rawConcept and/or narrative fields
2. Title requirement: These operations must also include a title field that becomes the .md filename
3. Path validation: Paths outside the project root are rejected

graph LR
    A[CurateOperation] --> B{Valid?}
    B -->|Missing Content| C[FAIL: operation requires content]
    B -->|Missing Title| D[FAIL: operation requires title]
    B -->|Valid| E[Execute Operation]
    E --> F[Write to .brv/context-tree/]
    F --> G[Trigger Abstract Generation Queue]

Abstract Generation System

The abstract generation system provides automated summarization of curated knowledge entries. It operates asynchronously through a queue-based architecture.

Generation Types

The abstract captures the core topic and key insight in a single complete sentence, while the overview provides detailed structure including key points (3-7 bullets), section summaries, and notable entities or decisions.

Sources: abstract-generator.ts:40-65

Batched Prompt Building

The system processes files in batches using XML-formatted prompts with CDATA wrapping to safely handle special characters:

<file path="path/to/file.md">
<document><![CDATA[file content here]]></document>
</file>

The wrapCdata function uses a standard CDATA-in-CDATA escape technique:

function wrapCdata(content: string): string {
  return `<![CDATA[${content.replaceAll(']]>', ']]]]><![CDATA[>')}]]>`
}

Sources: abstract-generator.ts:30-35

Response Parsing

The parser extracts <abstract> or <overview> tags from model responses using a robust regex approach anchored on <file path="..."> openers rather than closing tags. This prevents premature termination when the content naturally contains </file> sequences (common in documentation about XML, JSX, or build systems).

graph TD
    A[Model Response] --> B{Scan for <file path=...>}
    B -->|Found| C[Extract slice to next opener]
    C --> D[Extract inner tag content]
    D --> E[Map path to content]
    B -->|Not found| F[End of parsing]

Abstract Generation Queue

The AbstractGenerationQueue class manages background abstract generation with reliability features.

Queue Architecture

Queue Status

The queue exposes status through the AbstractQueueStatus interface:

interface AbstractQueueStatus {
  failed: number          // Items that failed after all retries
  pending: number         // Items waiting to be processed (including retry backoff)
  processed: number       // Successfully processed items
  processing: number      // Currently being processed
}

File Filtering

The queue automatically filters out certain file types to avoid generating redundant abstracts:

• context.md files (hierarchy scaffolding)
• _index.md files (auto-generated summaries)
• .abstract.md files (output files themselves)
• .overview.md files (output files themselves)

Sources: abstract-queue.ts:25-35

Knowledge Retrieval

ByteRover provides multiple mechanisms for retrieving stored knowledge during agent operations.

Expand Knowledge Tool

The expand-knowledge-tool enables retrieval of content from the Context Tree through two primary modes:

interface ExpandKnowledgeToolConfig {
  baseDirectory?: string           // Custom base directory
  runtimeSignalStore?: IRuntimeSignalStore  // Signal handling
}

The tool description clearly identifies its purpose:

"Retrieve full content from archived knowledge entries or L1 overview files. Use stubPath when search results include an archive_stub that you need to drill into. Use overviewPath to retrieve the structured overview for a context entry."

Sources: expand-knowledge-tool.ts:40-60

Query Commands

Query commands search only within the Context Tree structure, not the entire project. This ensures focused knowledge retrieval without noise from source code or unrelated files.

Knowledge Path Resolution

The system resolves knowledge paths relative to the project root (.brv/context-tree/), ensuring isolation from arbitrary file system access. Files outside this directory are not accessible through the knowledge system.

Storage Format

Knowledge File Structure

Individual knowledge entries are stored as Markdown files with structured frontmatter:

# Title

## Core Concept
[rawConcept content]

## Narrative
[narrative content]

## Metadata
- Created: timestamp
- Tags: [domain, topic]

Archive Format

Archived entries are stored in _archived/ subdirectories, maintaining the same file structure but segregated for reduced visibility in default queries. The expand_knowledge command with stubPath is required to drill into archived content.

Integration Points

With Agent System

The Context Tree integrates with the agent's query and curate capabilities through the swarm coordinator, enabling:

• Dynamic domain creation based on content semantics
• Conflict detection between new and existing knowledge
• Memory scoring for relevance-based retrieval

With Version Control

The .brv/context-tree/ directory is designed for version control integration:

• Files are human-readable Markdown
• Standard git operations apply
• Cloud sync via brv vc push and brv vc pull supports knowledge collaboration

With Sandbox Execution

The curate service runs within sandboxed environments, providing controlled access to the knowledge system. Operations are validated before execution, and results are tracked for audit purposes.

Configuration Options

Best Practices

1. Domain organization: Before creating new domains, verify existing domains cannot accommodate the content
2. Title conventions: Use descriptive titles that serve as meaningful filenames
3. Content structure: Include both rawConcept (concise summary) and narrative (detailed explanation) when possible
4. Archive management: Use the archive feature for low-importance entries to keep active knowledge focused
5. Batch operations: When curating multiple files, the queue's batching system optimizes LLM usage

Related Documentation

• SKILL.md - CLI command reference for brv curate and brv query
• folder-pack-executor.ts - Folder packing for knowledge extraction

Related Pages

Related topics: Context Tree and Knowledge Storage, Agent System

Version Control for Context

Version Control for Context (VC) provides git-based version control for ByteRover's knowledge base (context tree). It enables tracking, branching, committing, merging, and syncing curated knowledge using familiar git semantics, with all operations working locally without authentication. Remote sync with a team is optional.

Overview

ByteRover's Version Control system extends standard git functionality to manage the .brv/context-tree/ directory where curated knowledge is stored. This system allows users to track changes to their knowledge base, create feature branches for experimental knowledge curation, collaborate with team members through remote sync, and maintain a complete history of knowledge evolution.

The VC system is built on top of an abstracted git service layer that provides cross-platform git operations, with additional intelligence for knowledge-specific use cases like tracking abstract generations and managing context tree structure. Sources: src/shared/transport/events/vc-events.ts:1-50

Architecture

graph TD
    subgraph "User Interface Layer"
        CLI[CLI - brv vc]
        WebUI[WebUI]
        TUI[TUI Components]
    end
    
    subgraph "Command Layer"
        VCCommands[VC Commands]
        BranchCmd[Branch Command]
        CommitCmd[Commit Command]
        MergeCmd[Merge Command]
        PushCmd[Push Command]
    end
    
    subgraph "Service Layer"
        GitService[Git Service Interface]
        CurateService[Curate Service]
        CommandValidator[Command Validator]
    end
    
    subgraph "Infrastructure Layer"
        GitImpl[Isomorphic Git]
        FileSystem[File System]
        Events[VC Events Transport]
    end
    
    subgraph "Data Layer"
        ContextTree[.brv/context-tree/]
        GitStorage[Git Repository]
    end
    
    CLI --> VCCommands
    WebUI --> VCCommands
    TUI --> VCCommands
    
    VCCommands --> GitService
    VCCommands --> CommitCmd
    VCCommands --> BranchCmd
    VCCommands --> MergeCmd
    
    GitService --> GitImpl
    GitService --> FileSystem
    GitService --> Events
    
    CommitCmd --> ContextTree
    CurateService --> ContextTree
    
    ContextTree --> GitStorage
    GitImpl --> GitStorage

Diff Modes

The VC system supports four diff modes that mirror git diff semantics, allowing precise comparison of knowledge changes across different stages and references. Sources: src/shared/transport/events/vc-events.ts:16-27

export type VcDiffMode =
  | {from: string; kind: 'range'; to: string}
  | {kind: 'ref-vs-worktree'; ref: string}
  | {kind: 'staged'}
  | {kind: 'unstaged'}

Diff File Model

Each file entry in a diff response includes comprehensive metadata about the change. Sources: src/shared/transport/events/vc-events.ts:35-50

Binary files are filtered out of diff responses upstream, ensuring consumers only receive text content. Legacy WebUI consumers read oldContent, newContent, and path fields while ignoring additional fields for forward compatibility.

Git Service Interface

The IGitService interface defines the complete set of git operations available for version control. Sources: src/server/core/interfaces/services/i-git-service.ts:1-100

Core Methods

Blob Operations

The hashBlob method computes the 7-character short OID that git would assign to content, using git hash-object. This is essential for rendering working-tree diff headers since the working tree has no stored OID. Sources: src/server/core/interfaces/services/i-git-service.ts:20-27

Command Validation

Git operations executed through the sandbox are validated for security and safety. The command validator enforces patterns that control which git operations are permitted. Sources: src/agent/infra/process/command-validator.ts:1-50

Allowed Read-Only Operations

The following git operations are permitted in validated contexts:

/git\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\s+-)/i

Recommended Git Workflow

The bash execution guidelines recommend this workflow for git operations: Sources: src/agent/resources/tools/bash_exec.txt:1-30

1. Run git status to see changes
2. Run git diff to review changes
3. Stage files with git add
4. Commit with a meaningful message

For pull requests:

1. Check branch status with git status
2. Push to remote with git push -u origin <branch>
3. Create PR using gh pr create

Commit History Display

The WebUI provides a commit history panel that displays the timeline of knowledge changes. Sources: src/webui/features/context/components/context-history-panel.tsx:1-60

function formatCommitDate(timestamp: string): string {
  try {
    return `Updated at ${format(new Date(timestamp), 'MMM d, HH:mm')}`
  } catch {
    return 'Updated'
  }
}

The history panel renders timeline items with:

• Commit author name
• Timestamp formatted as "MMM d, HH:mm"
• Visual distinction between current commit (active) and older commits

Push Flow

The TUI push flow handles the process of pushing commits to remote repositories. It includes remote URL validation and status display during the push operation. Sources: src/tui/features/vc/push/components/vc-push-flow.tsx:1-80

return (
  <Text>
    <Spinner type="dots" /> {branch ? `Pushing to origin/${branch}...` : 'Pushing...'}
  </Text>
)

The push flow requires:

• Remote URL configuration
• Remote URL validation before submission
• Branch name determination for the push target

Context Tree Structure

The context tree is organized in .brv/context-tree/ and includes version control information in system prompts. Sources: src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-100

Structure Rules

• Each top-level folder is a domain (dynamically created based on content)
• Inside domains are topics as .md files or subfolders with context.md
• context.md files contain the curated knowledge content
• _index.md files are auto-generated summaries at each directory level
• _archived/ contains archived low-importance entries

Domain Management

Domains are created dynamically based on the semantics of curated content. Domain names use snake_case (e.g., architecture, market_trends, risk_analysis). Before creating a new domain, the system checks if existing domains could accommodate the content.

VC Integration

The system prompt contributor includes version control information:

• Query commands search only within the context tree structure
• Curate commands check existing domains/topics before creating new ones
• Archived entries can be accessed using expand_knowledge to drill into them

Workflow Diagram

graph LR
    subgraph "Local Operations"
        A[Curate Knowledge] --> B[brv vc add]
        B --> C[brv vc commit]
        C --> D[brv vc status]
        D --> E{Changes?}
        E -->|Yes| F[Review Changes]
        E -->|No| G[Done]
        F --> H[brv vc log]
    end
    
    subgraph "Branch Management"
        I[brv vc branch feature/auth] --> J[brv vc checkout feature/auth]
        J --> K[Develop Knowledge]
        K --> L[brv vc merge]
    end
    
    subgraph "Remote Sync"
        M[brv vc push] --> N[brv vc pull]
        N --> O[brv vc fetch]
    end
    
    H --> I
    L --> M

Key Features Summary

Remote Operations

Remote sync requires ByteRover authentication (brv login) and a configured remote. The following operations are supported:

Related Documentation

• ByteRover CLI Template System - Agent instruction generation
• Curate Service - Knowledge curation operations
• Context Tree Structure Contributor - System prompt integration

Related Pages

Related topics: System Architecture Overview

WebUI Dashboard

The WebUI Dashboard is a React-based web interface served locally by the ByteRover daemon, providing developers with a graphical way to interact with the ByteRover CLI system. It serves as the primary user-facing component for managing AI coding agents, version control operations, context knowledge bases, task monitoring, and provider configurations through a modern, dark-themed interface.

Architecture Overview

The WebUI operates as a client-side React application that communicates with the server-side daemon via a WebSocket-based transport layer. The architecture follows a feature-based folder structure where related components, hooks, and utilities are co-located.

graph TD
    Client["WebUI Client<br/>(React + Tailwind)"]
    Server["WebUI Server<br/>(webui-server.ts)"]
    API["API Client<br/>(api-client.ts)"]
    Transport["WebSocket Transport"]
    Daemon["ByteRover Daemon"]
    Providers["LLM Providers"]
    
    Client --> API
    API --> Transport
    Transport --> Server
    Server --> Daemon
    Server --> Providers
    
    subgraph WebUI_Features ["WebUI Features"]
        Context["Context/Knowledge Management"]
        Tasks["Task Monitoring"]
        VC["Version Control"]
        Providers["Provider Configuration"]
        Hub["Hub/Marketplace"]
        Project["Project Management"]
    end
    
    Client --> Context
    Client --> Tasks
    Client --> VC
    Client --> Providers
    Client --> Hub
    Client --> Project

Core Components

Header Layout

The header.tsx file defines the main navigation header component that provides persistent access to key functionality across all pages.

Key Features:

Sources: src/webui/layouts/header.tsx:1-60

<TooltipTrigger
  render={
    <Button
      className={cn('whitespace-nowrap', triggerToneClass)}
      onClick={() => setProviderDialogOpen(true)}
      size="sm"
      variant="ghost"
    />
  }
>
  <span className="relative mr-1 inline-flex size-4 shrink-0">
    <Plug className="size-4" />
    {activeProvider && (
      <StatusDot
        className="border-background absolute -right-0.5 -bottom-0.5 size-2 border-2"
        tone={isByteRoverActive && needsPickPrompt ? 'amber' : STATUS_DOT_TONE[billingTone]}
      />
    )}
  </span>
  {providerLabel}
</TooltipTrigger>

Page Routing

The application uses file-based routing through router.tsx, mapping URL paths to React page components. The router serves as the central navigation hub, enabling deep linking and browser history integration.

Sources: src/webui/router.tsx

Feature Panels

Context/Knowledge Management

The context panel provides an interface for managing the knowledge base used by AI agents. It displays the curated knowledge topics, allows navigation through the context tree structure, and shows search functionality.

Sources: src/webui/features/context/components/context-layout.tsx

Key operations supported:

• View knowledge topics organized in a tree structure
• Search and filter within the knowledge base
• Expand/collapse topic hierarchies
• Navigate to detailed topic views

Task Monitoring

The task list view component displays active, completed, and failed tasks from the agent execution history. It integrates with the task history system defined in the server domain layer.

Sources: src/webui/features/tasks/components/task-list-view.tsx

The TUI's expanded log view provides a reference for expected task display behavior:

{log.status === 'completed' && (
  <Box paddingX={1}>
    <ExecutionChanges
      created={log.changes.created}
      isExpanded
      maxChanges={{
        created: Number.MAX_SAFE_INTEGER,
        updated: Number.MAX_SAFE_INTEGER,
      }}
      updated={log.changes.updated}
    />
  </Box>
)}

Sources: src/tui/components/execution/expanded-log-view.tsx:60-70

Version Control Panel

The VC components handle git-like operations including push and pull functionality. The UI provides visual feedback during sync operations and handles remote URL configuration.

Sources: src/webui/features/vc/components/remotes-panel.tsx

Push Flow States:

Sources: src/tui/features/vc/push/components/vc-push-flow.tsx:40-50

Provider Configuration

The providers panel enables users to configure LLM providers, set API keys, and manage OAuth authentication flows. It supports multiple authentication methods and provides validation before saving.

Sources: src/webui/features/provider/components/providers-panel.tsx

<div className="flex flex-wrap gap-2.5">
  <Button onClick={() => handleValidate(provider.id)} size="lg" variant="outline">
    Validate key
  </Button>
  <Button onClick={() => handleConnect(provider.id)} size="lg">
    Connect provider
  </Button>
</div>

#### OAuth Callback Handling

OAuth flows use a dedicated callback server that displays success or error pages:

function successHtml(): string {
  return `<!DOCTYPE html>
<html>
<head><title>ByteRover - Authorization Successful</title></head>
<body>
  <h1>Successful</h1>
  <p>You can close this window and return to ByteRover.</p>
  <script>setTimeout(() => window.close(), 2000);</script>
</body>
</html>`
}

Sources: src/server/infra/provider-oauth/callback-server.ts:1-30

Hub/Marketplace

The hub panel provides access to a marketplace of agent skills and capabilities. Users can browse available entries, select target agents, and install new functionality.

Sources: src/webui/features/hub/components/hub-panel.tsx

Project Management

The project dropdown component allows switching between different project workspaces, displaying project names and remote space associations.

Sources: src/webui/features/project/components/project-dropdown.tsx

const remoteLabel = teamName && spaceName ? `${teamName} / ${spaceName}` : undefined

<DropdownMenuItem className="gap-2 rounded-md" onClick={onSelect}>
  <ProjectItemRow name={name} project={project} remoteLabel={remoteLabel} />
</DropdownMenuItem>

API Communication

The WebUI communicates with the server through the API client located in src/webui/lib/api-client.ts. This client handles:

• RESTful API calls for CRUD operations
• WebSocket connection management for real-time updates
• Authentication token handling
• Error response normalization

Sources: src/webui/lib/api-client.ts

Offline Handling

When the connection to the daemon is lost, the WebUI displays an offline screen with reconnection status:

footer={
  <>
    {isConfigError ? (
      <span className="text-muted-foreground/80 text-xs">Refresh once the host is back.</span>
    ) : (
      <>
        <span aria-hidden className="bg-muted-foreground/60 size-1.5 animate-pulse rounded-full" />
        <span className="text-muted-foreground text-xs">
          Reconnecting<span className="opacity-60"> · attempt </span>
          <span className="text-foreground tabular-nums">{reconnectCount}</span>
        </span>
      </>
    )}
  </>
}

Sources: src/webui/features/transport/components/offline-screen.tsx:50-70

WebUI Server

The server-side component (webui-server.ts) hosts the React application, serves static assets, and manages WebSocket connections for real-time communication with the client.

Sources: src/server/infra/webui/webui-server.ts

Styling System

The WebUI uses Tailwind CSS with custom CSS variables for theming. The dark theme follows GitHub's design language with a cohesive color system:

:root {
  --bg: #0d1117;
  --bg-secondary: #161b22;
  --bg-tertiary: #21262d;
  --border: #30363d;
  --text: #e6edf3;
  --text-muted: #8b949e;
  --green: #238636;
  --red: #da3633;
  --blue: #58a6ff;
  --yellow: #d29922;
}

Sources: src/webui/styles/index.css:1-30

Typography

The application uses Geist for sans-serif text and JetBrains Mono for monospace/code display:

--font-sans: 'Geist', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Helvetica Neue', sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace;

HITL Review UI

The WebUI also includes a standalone HITL (Human-in-the-Loop) review interface served by the HTTP server for reviewing agent operations before committing changes:

export function getReviewPageHtml(): string {
  return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ByteRover Review</title>
<style>
  :root {
    --bg: #0d1117;
    --bg-secondary: #161b22;
    /* ... additional styles */
  }
</style>

Sources: src/server/infra/http/review-ui.ts:1-30

State Management

The WebUI follows a pattern where:

1. Local State: Component-specific state managed via React hooks (useState)
2. Server State: Data fetched and cached through query utilities (useGetProjectConfig, etc.)
3. Transport State: Connection status managed by the transport layer

graph LR
    subgraph State ["State Layers"]
        Local["Local UI State<br/>(useState)"]
        Server["Server State<br/>(useQuery)"]
        Transport["Transport State<br/>(WebSocket)"]
    end
    
    Local --> UI["React Components"]
    Server --> UI
    Transport --> UI

Data Flow

User interactions trigger the following flow:

1. User action in WebUI component
2. Component calls API client method
3. API client sends request via transport layer
4. Server processes request and returns response
5. React query cache updates
6. Components re-render with new data

Summary

The WebUI Dashboard provides a comprehensive graphical interface for all ByteRover CLI operations. Its modular architecture allows independent feature development while maintaining consistent styling and interaction patterns. The dark theme, real-time updates, and thoughtful error handling create a professional developer experience aligned with modern IDE design principles.

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite

• Severity: high
• Finding: Installation risk is backed by a source signal: Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/issues/647

2. Installation risk: Visual corruption while browsing a long model list

• Severity: high
• Finding: Installation risk is backed by a source signal: Visual corruption while browsing a long model list. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/issues/620

3. Installation risk: ByteRover CLI 3.10.1

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.10.1. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1

4. Installation risk: ByteRover CLI 3.10.3

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.10.3. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3

5. Installation risk: ByteRover CLI 3.8.1

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.8.1. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1

6. Installation risk: ByteRover CLI 3.8.2

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.8.2. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2

7. Installation risk: ByteRover CLI 3.8.3

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.8.3. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3

8. Installation risk: ByteRover CLI 3.9.0

• Severity: medium
• Finding: Installation risk is backed by a source signal: ByteRover CLI 3.9.0. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0

9. Installation risk: `brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours

• Severity: medium
• Finding: Installation risk is backed by a source signal: brv mcp client stuck in infinite exception loop consuming 75–90% CPU for hours. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/campfirein/byterover-cli/issues/660

10. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.

11. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing

12. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using byterover-cli with real data or production workflows.

• brv mcp client stuck in infinite exception loop consuming 75–90% CPU f - github / github_issue
• Visual corruption while browsing a long model list - github / github_issue
• Curator can copy prompt example facts into the context tree when using G - github / github_issue
• ByteRover CLI 3.12.0 - github / github_release
• ByteRover CLI 3.11.0 - github / github_release
• ByteRover CLI 3.10.3 - github / github_release
• ByteRover CLI 3.10.2 - github / github_release
• ByteRover CLI 3.10.1 - github / github_release
• ByteRover CLI 3.10.0 - github / github_release
• ByteRover CLI 3.9.0 - github / github_release
• ByteRover CLI 3.8.3 - github / github_release
• ByteRover CLI 3.8.2 - github / github_release