Skip to main content

​
The Problem

Real-world projects rarely live in a single directory. Monorepos contain multiple packages. Git worktrees create parallel checkouts. Related services live in separate repositories. Without multi-project support, each directory gets its own .brv/ context tree — forcing teams to curate the same knowledge multiple times. ByteRover solves this with two complementary features:
FeaturePurposeRelationship
WorktreeLink subdirectories to a parent projectOne knowledge base, many directories
SourceReference knowledge from other projectsRead-only cross-project search

​
When to Use Each

​
Worktrees — Same Project, Multiple Directories

Use worktrees when directories belong to the same logical project and should share a single context tree. Common scenarios:
  • Monorepo packages — packages/api/, packages/web/, packages/shared/ all share the monorepo’s curated knowledge
  • Git worktrees — Parallel checkouts of the same repo for concurrent work
  • Sibling checkouts — Multiple clones of the same project
cd /monorepo
brv worktree add packages/api
brv worktree add packages/web
After setup, running brv query from packages/api/ searches the monorepo’s context tree — no duplication needed.

​
Sources — Different Projects, Shared Knowledge

Use sources when you want to reference knowledge from another project without copying it. Common scenarios:
  • Platform team patterns — Your product repo references the auth service’s curated patterns
  • Shared libraries — Multiple consumers reference the library’s documented conventions
  • Design systems — Frontend repos reference the design system’s component guidelines
cd /product-repo
brv source add /path/to/auth-service --alias auth
brv source add /path/to/design-system --alias design
After setup, brv query "JWT validation" searches your local context tree plus both sources, with results attributed to their origin.

​
How They Work Together

The real power emerges when combining both features: 
monorepo/                             # main brv project
  .brv/
    ├── context-tree/                 # curated once
    ├── sources.json                  # references design-system
    └── worktrees/
        ├── packages-api/link.json
        └── packages-web/link.json
  packages/api/
    .brv                              # pointer file -> monorepo
  packages/web/
    .brv                              # pointer file -> monorepo

design-system/                        # separate project
  .brv/
    └── context-tree/                 # component patterns
From packages/api/:
  1. ByteRover follows the .brv pointer to the monorepo
  2. Searches the monorepo’s context tree (local knowledge)
  3. Searches the design system’s context tree (shared source)
  4. Returns results with origin attribution: [design]:components/button.md

​
Key Design Principles

  • No duplication — Worktrees point to the parent’s context tree; sources reference in-place. Nothing is copied.
  • Git-style mental model — Worktree pointers use the same .brv file/directory duality that Git uses for .git in worktrees.
  • Read-only sources — Sources are never modified through the referencing project. Write guards prevent accidental mutations.
  • Origin attribution — Query results always show where knowledge came from, so you know the source.
  • No sync required — Both features are declarative references, not sync mechanisms. Changes in the target are immediately visible.

​
Next Steps

Worktrees

Link directories to share a single context tree across your workspace

Sources

Reference knowledge from other projects with read-only cross-project search