Overview

Share curated knowledge across monorepos, git worktrees, and independent projects

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:

Feature	Purpose	Relationship
Worktree	Link subdirectories to a parent project	One knowledge base, many directories
Source	Reference knowledge from other projects	Read-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