byterover-cli Documentation

Technical Documentation: campfirein/byterover-cli

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

ByteRover CLI

Overview Copy Chapter

ByteRover CLI (brv) gives AI coding agents persistent, structured memory. It lets developers curate project knowledge into a context tree, sync it to the cloud, and share it across tools and teammates.

Run brv in any project directory to start an interactive REPL powered by your choice of LLM. The agent understands your codebase through an agentic map, can read and write files, execute code, and store knowledge for future sessions.

📄 Read the paper for the full technical details.

Or download our self-hosted PDF version of the paper here.

Key Features:

• 🌐 Web dashboard for curating and querying context (brv webui)
• 🖥️ Interactive TUI with REPL interface (React/Ink)
• 🧠 Context tree and knowledge storage management
• 🔀 Git-like version control for the context tree (branch, commit, merge, push/pull)
• 🤖 20 LLM providers (Anthropic, OpenAI, Google, Groq, Mistral, xAI, DeepSeek, and more)
• 🛠️ 24 built-in agent tools (code exec, file ops, knowledge search, memory management)
• 🔄 Cloud sync with push/pull
• 👀 Review workflow for curate operations (approve/reject pending changes)
• 🔌 MCP (Model Context Protocol) integration
• 📦 Hub and connectors ecosystem for skills and bundles
• 🤝 Works with 22+ AI coding agents (Cursor, Claude Code, Windsurf, Cline, and more)
• 🏢 Enterprise proxy support

Benchmark Results Copy Chapter

All benchmarks are run using the production byterover-cli codebase in this repository - no separate research prototype.

We evaluate on two long-term conversational memory benchmarks:

• LoCoMo - ultra-long conversations (~20K tokens, 35 sessions) testing single-hop, multi-hop, temporal, and open-domain retrieval.
• LongMemEval-S - large-scale benchmark (23,867 docs, ~48 sessions per question) testing 6 memory abilities including knowledge update, temporal reasoning, and multi-session synthesis.

LoCoMo - 96.1% overall accuracy (1,982 questions, 272 docs).

LongMemEval-S - 92.8% overall accuracy (500 questions, 23,867 docs).

All metrics are LLM-as-Judge accuracy (%). See the paper, or self-hosted PDF for full details.

Quick Start Copy Chapter

Shell Script (macOS & Linux) Copy Section

No Node.js required - everything is bundled.

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

Supported platforms: macOS ARM64, macOS x64 (Intel), Linux x64, Linux ARM64.

npm (All Platforms) Copy Section

Requires Node.js >= 20.

npm install byterover-cli

Verify Copy Section

brv --version

First Run Copy Section

cd your/project
brv

The REPL auto-configures on first run - no setup needed. Type / to discover all available commands:

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

ByteRover Cloud Copy Chapter

ByteRover Cloud is a hosted platform for teams to sync, share, and manage context knowledge across projects and machines.
Everything works locally by default - Cloud adds collaboration and persistence without changing your workflow.

Sign in from the dashboard, or run brv login with an API key.

• 🔄 Team context sync — push and pull shared knowledge across teammates
• 📂 Shared spaces — organize context across multiple projects and teams
• 💻 Multi-machine access — sync your context tree across devices with cloud backup
• 💻 Multi-machine access — sync your context tree across devices
• 🧠 Built-in hosted LLM — start immediately with limited free usage
• 👥 Team management — manage members, spaces, and permissions via the web app
• 📊 Usage analytics — track seat allocation and monthly credit consumption
• 🔒 SOC 2 Type II certified infrastructure with privacy mode

CLI Usage

Most users only need brv webui. The commands below are for advanced users and automation. Run brv --help for the full, up-to-date reference.

Core Workflow Copy Section

brv                  # Start interactive REPL
brv webui            # Open the ByteRover dashboard (primary UI)
brv status           # Show project and daemon status
brv curate           # Add context to knowledge storage
brv curate view      # View curate history
brv query            # Query context tree and knowledge
brv review pending   # List pending review operations
brv review approve   # Approve curate operations
brv review reject    # Reject curate operations

Sync (Legacy) Copy Section

brv push             # Legacy — migrate or snapshot context to cloud
brv pull             # Legacy — restore context from cloud snapshot

Use brv vc push / brv vc pull for version-controlled sync going forward.

Version Control Copy Section

brv vc init              # Initialize version control for context tree
brv vc status            # Show version control status
brv vc add               # Stage files for the next commit
brv vc commit            # Save staged changes as a commit
brv vc log               # Show commit history
brv vc branch            # List, create, or delete branches
brv vc checkout          # Switch branches
brv vc merge             # Merge a branch into the current branch
brv vc clone             # Clone a ByteRover space repository
brv vc push              # Push commits to ByteRover cloud
brv vc pull              # Pull commits from ByteRover cloud
brv vc fetch             # Fetch refs from ByteRover cloud
brv vc remote            # Show current remote origin
brv vc remote add        # Add a named remote
brv vc remote set-url    # Update a remote URL
brv vc config            # Get or set commit author
brv vc reset             # Unstage files or undo commits

Providers & Models Copy Section

brv providers list       # List available LLM providers
brv providers connect    # Connect to an LLM provider
brv providers switch     # Switch active provider
brv providers disconnect # Disconnect a provider
brv model list           # List available models
brv model switch         # Switch active model

Hub & Connectors Copy Section

brv hub list             # List available hub packages
brv hub install          # Install a hub package
brv hub registry add     # Add a custom registry
brv hub registry list    # List registries
brv hub registry remove  # Remove a registry
brv connectors list      # List connectors
brv connectors install   # Install a connector

Spaces (Deprecated) Copy Section

brv space list       # Deprecated — use web dashboard
brv space switch     # Deprecated — use brv vc clone

Settings Copy Section

brv ships with operational defaults that suit most users. The brv settings command group lets you inspect and override these values.

brv settings                    # List all settings with current and default values
brv settings list               # Alias for `brv settings`
brv settings get <key>          # Show current and default for one key
brv settings set <key> <value>  # Update one key (restart required)
brv settings reset <key>        # Restore one key to its default (restart required)

Available keys:

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 instead of waiting out the full budget. The cap is enforced per task, not per request.

llm.requestTimeoutMs bounds one HTTP request to the LLM. A frozen Ollama or LM Studio connection aborts at this boundary and the retry layer treats it as a transient error rather than wasting the full iteration budget. The setting must satisfy llm.requestTimeoutMs <= llm.iterationBudgetMs; the daemon rejects writes that violate the rule and falls back to defaults for both keys when the file violates it at startup. Suggested presets:

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

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

Changes apply after brv restart. The daemon reads the file once at startup and does not observe file changes during runtime. This keeps every running agent on the same configuration for the lifetime of the daemon.

Example session:

$ brv settings list
KEY                                       CURRENT  DEFAULT  RESTART?
agentPool.maxSize                         10       10       yes
agentPool.maxConcurrentTasksPerProject    5        5        yes
taskHistory.maxEntries                    1000     1000     yes

$ brv settings set agentPool.maxSize 20
Setting saved. Run `brv restart` to apply.

$ brv settings get agentPool.maxSize
20  (default: 10)

Every command supports --format json for scripting. Validation errors (unknown key, value out of range) exit with code 1 and a message naming the key.

Other Copy Section

brv mcp              # Start MCP server
brv login            # Authenticate to ByteRover
brv logout           # Disconnect and clear credentials
brv locations        # List registered projects
brv restart          # Restart daemon
brv debug            # Debug mode

Run brv --help for the full command reference.

Supported LLM Providers

ByteRover CLI supports 20 LLM providers out of the box. Connect and switch providers from the dashboard, or use brv providers connect / brv providers switch.

Worktrees and Knowledge Sources Copy Chapter

Vocabulary

• Worktree link — a subdirectory pointer to a parent project (brv worktree)
• Source — a read-only reference to another project's knowledge (brv source)
• Origin — where an indexed search result came from (local vs shared)

ByteRover can run from a linked subdirectory without creating a nested .brv/.

• projectRoot: the directory that owns .brv/config.json
• worktreeRoot: the linked worktree directory, or projectRoot when unlinked
• clientCwd: the shell cwd where you ran brv

When you run brv query or brv curate from a linked worktree, implicit defaults use worktreeRoot so scope stays stable even if clientCwd drifts deeper into the package. Explicit relative paths that you pass yourself, such as brv curate -f ./src/auth.ts, still resolve from clientCwd to match normal shell behavior.

Use brv worktree add from the project root to register a subdirectory (or sibling) as a worktree. This creates a .brv pointer file in the target directory that redirects to the parent project — the same pattern git uses for git worktree. Use brv worktree remove to unregister, and brv worktree list to inspect. To search another project's knowledge from here, use brv source add (with brv source list / brv source remove to inspect or detach).

Documentation Copy Chapter

Visit docs.byterover.dev for full guides on setup, integrations, and advanced usage.

Contributing Copy Chapter

We welcome contributions! See our Contributing Guide for development setup, coding standards, and the PR workflow.

Community & Support Copy Chapter

ByteRover CLI is built and maintained by the ByteRover team.

• Join our Discord to share projects, ask questions, or just say hi
• Report issues on GitHub
• If you enjoy ByteRover CLI, please give us a star on GitHub — it helps a lot!
• Follow @kevinnguyendn on X

Contributors Copy Chapter

Star History Copy Chapter

License Copy Chapter

Elastic License 2.0. See LICENSE for full terms.

Overview (`paper/README.md`) Copy Section

ByteRover: Agent-Native Memory Through LLM-Curated Hierarchical Context

Research paper for ByteRover - an agent-native memory architecture where the LLM itself curates, structures, and retrieves knowledge through a hierarchical Context Tree, requiring zero external infrastructure.

All benchmarks are run using the production byterover-cli codebase in this repository - no separate research prototype.

Results Copy Chapter

We evaluate on two long-term conversational memory benchmarks:

• LoCoMo - ultra-long conversations (~20K tokens, 35 sessions) testing single-hop, multi-hop, temporal, and open-domain retrieval.
• LongMemEval-S - large-scale benchmark (23,867 docs, ~48 sessions per question) testing 6 memory abilities including knowledge update, temporal reasoning, and multi-session synthesis.

LoCoMo - 96.1% overall accuracy (1,982 questions, 272 docs).

LongMemEval-S - 92.8% overall accuracy (500 questions, 23,867 docs).

All metrics are LLM-as-Judge accuracy (%).

Building the PDF Copy Chapter

# Requires BasicTeX or MacTeX
# Install: brew install --cask basictex
# Then: sudo tlmgr install multirow algorithms algorithmic enumitem float tcolorbox environ trimspaces listings subcaption natbib tabularx

bash build.sh    # Build PDF
make clean       # Remove build artifacts

File Structure Copy Chapter

Overview (`src/server/templates/README.md`) Copy Section

ByteRover CLI Template System

This directory contains template files used to generate agent instructions via the brv gen-rules command.

Directory Structure Copy Chapter

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 Files Copy Chapter

`base.md` Copy Section

The main template structure that combines all sections into the final output.

Variables:

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

`sections/workflow.md` Copy Section

Complete guide to the context tree workflow:

• Quick start examples
• Command reference for context management
• Best practices for using context tree
• Examples with real use cases

`sections/command-reference.md` Copy Section

Comprehensive documentation of all BR CLI commands:

• Root commands (login, init, status, add, gen-rules, push, watch, cipher-agent)
• Space commands (list, switch)

Each command includes:

• Description
• Arguments (if any)
• Flags with defaults
• Examples

How It Works Copy Chapter

1. User runs brv gen-rules
2. User selects an agent (e.g., "Claude Code")
3. RuleTemplateService loads templates via FsTemplateLoader
4. Templates are assembled:
   • Load section templates (workflow, command-reference)
   • Substitute variables in base template
   • Combine all content
5. Output written to .clinerules/byterover-rules.md

Variable Substitution Copy Chapter

The template system supports simple variable substitution using {{variable_name}} syntax.

Available Variables:

• {{agent_name}} - Agent name selected by user

Updating Templates Copy Chapter

To Update Command Documentation: Copy Section

Edit sections/command-reference.md - changes will be reflected next time brv gen-rules runs.

To Update Context Tree Workflow Guide: Copy Section

Edit sections/workflow.md - changes will be reflected next time brv gen-rules runs.

To Change Output Structure: Copy Section

Edit base.md - modify how sections are combined.

Best Practices Copy Chapter

1. Keep templates in sync with code: When adding/modifying commands, update command-reference.md
2. Use clear examples: Show realistic use cases in examples
3. Maintain markdown formatting: Ensure proper headers, code blocks, and lists
4. Test after changes: Run brv gen-rules and verify output in .clinerules/byterover-rules.md

Future Enhancements Copy Chapter

This template system is designed to support future improvements:

• Context-aware content (show different sections based on project state)
• Agent-specific customizations (per-agent template overrides)
• Conditional sections (e.g., show memory commands only if authenticated)
• Dynamic variable injection (project status, context tree stats, etc.)

Technical Details Copy Chapter

Template Loader: src/infra/template/fs-template-loader.ts

• Loads templates from filesystem
• Performs variable substitution
• Returns assembled content

Template Service: src/infra/rule/rule-template-service.ts

• Orchestrates template loading
• Builds final instruction content
• Injects agent-specific values

Command: src/commands/gen-rules.ts

• User-facing command
• Prompts for agent selection
• Writes output to .clinerules/byterover-rules.md

Curate Protocol (`docs/curate-protocol.md`) Copy Section

`brv curate` tool-mode session protocol

The session protocol lets a calling agent (Claude Code, Cursor, etc.) drive brv curate without byterover holding any LLM provider config. ByteRover orchestrates the multi-step flow; the calling agent supplies LLM completions across multiple CLI invocations.

This document defines the wire contract: CLI surface, JSON envelope, lifecycle. SKILL.md authors and other tool consumers key off the shapes documented here.

CLI surface Copy Chapter

Kickoff Copy Section

brv curate "<user intent>" --format json

Tool mode is the only path for brv curate — no provider configuration, no env-var opt-in.

Continuation — `--session` carries the prior call's id Copy Section

The continuation payload is always a JSON envelope of the form {"html": "...", "meta": {...}}. Two equivalent ways to deliver it:

# Inline envelope on --response
brv curate --session <sessionId> --response '{"html":"<bv-topic>...</bv-topic>","meta":{...}}' --format json

# Envelope from a JSON file via --response-file (mutually exclusive with --response)
brv curate --session <sessionId> --response-file envelope.json --format json

# Same, with opt-in cleanup once the daemon dispatch returns
brv curate --session <sessionId> --response-file envelope.json --delete-response-file --format json

Presence of --session resumes an in-flight session created by a prior kickoff. --response-file - (stdin) is not supported in v1.

--delete-response-file lifecycle. The file is unlinked after the daemon dispatch returns, not before. A daemon-error throw (transport timeout, daemon down) skips the unlink entirely so the agent retains the envelope for retry. A non-throw return (done, correct-html, or any other status) honors the unlink. One consequence: on a correct-html continuation the source file is gone but the session is still live — the calling agent must re-author a fresh envelope and write a new file before the next continuation. The inline --response flow has no equivalent re-authoring tax.

Overwrite intent — `--overwrite` on continuation Copy Section

brv curate --session <sessionId> --response-file envelope.json --overwrite --format json

Default behavior: the writer refuses to clobber an existing topic at the resolved path and returns a path-exists correction step carrying the prior file's content. Pass --overwrite only when the calling agent has consciously decided to replace prior content. The flag is consumed on the continuation it appears on; subsequent continuations in the same session must repeat it if they still want to overwrite.

`--format text` fallback Copy Section

Both kickoff and continuation accept --format text for shell users. The output is a terse human digest. The primary consumer (the calling agent) uses --format json.

Wire envelope Copy Chapter

Every kickoff and continuation call returns the same JSON envelope under the standard CLI wrapper:

{
  "command": "curate",
  "success": <ok>,
  "data": {
    "ok": <bool>,
    "status": "done" | "needs-llm-step" | "failed",
    "sessionId": "<uuid>",       // present on needs-llm-step AND on transient failed (see below)
    "step": "generate-html" | "correct-html",
    "prompt": "<free-text>",      // free-text instruction for the calling agent's LLM
    "schema": { ... },            // optional per-step schema slice
    "errors": [                   // present on correct-html, on failed, AND on done envelopes that carry a non-fatal companion error (today only --delete-response-file cleanup failure — see response-file-delete-error row below)
      {
        "kind": "<machine-readable>",
        "tag": "<bv-element>?",
        "attribute": "<attribute-name>?",
        "message": "<human-readable>"
      }
    ],
    "filePath": "<relative-path>",  // relative to .brv/context-tree/; present when status = done
    "warnings": [ "<advisory>" ]    // optional, only on done envelopes; non-fatal post-write notes from the writer
  },
  "timestamp": "<iso>"
}

Status values Copy Section

`step` values (when `status === 'needs-llm-step'`) Copy Section

Error `kind` values Copy Section

Terminal vs transient. Terminal failures end the session — the caller cannot retry the same sessionId and must start a new kickoff. Transient failures keep the session alive on disk; the envelope echoes the sessionId back and the caller is expected to issue a corrected continuation against it.

Retry cap. Each transient correction increments an internal attempts counter on the session. After MAX_ATTEMPTS = 4 consecutive invalid responses (the initial generate plus three corrections) the orchestrator terminates with retry-cap-exceeded and clears the session. Calling agents should surface this as "I couldn't produce valid HTML after several attempts; want to try a different framing?".

Calling agents should switch on kind, fall back gracefully on unknown kinds, and surface the message text to the user.

Lifecycle — worked example Copy Chapter

A complete tool-mode curate session, end-to-end:

1. Kickoff Copy Section

brv curate "remember we decided to use RS256" --format json

Response (placeholder):

{
  "command": "curate",
  "success": true,
  "data": {
    "ok": true,
    "status": "needs-llm-step",
    "sessionId": "8c3f9e2a-...",
    "step": "generate-html",
    "prompt": "Generate a <bv-topic>...</bv-topic> HTML document for the following user intent:\n\nremember we decided to use RS256\n\n..."
  },
  "timestamp": "2026-05-11T12:00:00.000Z"
}

2. Calling agent's LLM produces HTML Copy Section

<bv-topic path="security/auth" title="JWT signing algorithm">
  <bv-decision id="d-rs256">Use RS256 over HS256.</bv-decision>
</bv-topic>

3. Continuation Copy Section

brv curate --session 8c3f9e2a-... --response '{"html":"<bv-topic ...>...</bv-topic>","meta":{"type":"ADD","impact":"high","reason":"Locks JWT alg.","summary":"JWT: RS256."}}' --format json
# Or with the envelope on disk:
brv curate --session 8c3f9e2a-... --response-file envelope.json [--delete-response-file] --format json

Response on a valid HTML topic:

{
  "command": "curate",
  "success": true,
  "data": {
    "ok": true,
    "status": "done",
    "filePath": "security/auth.html"
  },
  "timestamp": "2026-05-11T12:00:01.000Z"
}

If validation fails (e.g. the agent forgot path= on ``), the envelope instead carries status: "needs-llm-step", step: "correct-html", and errors[] for the calling agent to fix. Up to 3 corrections (MAX_ATTEMPTS = 4 total) before terminal status: "failed" with kind: retry-cap-exceeded.

Session storage Copy Chapter

CLI-side. Per-project, on disk at /.brv/sessions/curate-<sessionId>/state.json. State carries attempts, step (awaiting-generate vs awaiting-correct), and the last response (for the correction prompt). State is removed when the session reaches terminal done or terminal failed (including retry-cap-exceeded).

Abandoned sessions are not yet pruned — a 1-hour TTL is a planned follow-up that pairs with moving state into the daemon's existing task-session lifecycle.

Stability promise Copy Chapter

SKILL.md ships against this envelope, so renaming any key here is a breaking change. New error kinds and new step values can be added without breaking existing consumers — calling agents are expected to gracefully ignore unknown values.

What's not the protocol's job Copy Chapter

• HTML generation. Calling agent's LLM authors the HTML per the prompt. Byterover never touches an LLM in tool mode.
• Schema knowledge. Embedded in the prompt (the prompt builder condenses the bv-* spec). Calling agent doesn't pre-load any schema.
• Retry strategy beyond the protocol's correct-html loop. If the calling agent's LLM keeps producing invalid HTML for 3 rounds, the session terminates failed — the calling agent surfaces this and falls back to asking the user for clarification.

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~8464 tokens
• Canonical Reference: https://codewiki.google/github.com/campfirein/byterover-cli