Skip to main content

​
What Are Sources?

Sources let you reference curated knowledge from other ByteRover projects. When you add a source, its context tree becomes searchable alongside your own — without copying any data. Results are attributed to their origin so you always know where knowledge came from. This is useful when:
  • Platform teams share auth patterns, infrastructure conventions, or API guidelines
  • Shared libraries document their conventions for downstream consumers
  • Design systems provide component guidelines to frontend teams
  • Cross-team collaboration requires visibility into each other’s curated knowledge

​
How It Works

Sources are declarative, one-way references stored in your project’s .brv/sources.json. Nothing is written to the target project — it doesn’t even know you’ve referenced it. 
your-project/.brv/
  ├── config.json
  ├── context-tree/              # your local knowledge
  └── sources.json               # references to other projects
sources.json structure: 
{
  "version": 1,
  "sources": [
    {
      "alias": "auth",
      "projectRoot": "/path/to/auth-service",
      "addedAt": "2026-04-10T12:00:00.000Z",
      "readOnly": true
    }
  ]
}
When you run a query, ByteRover searches:
  1. Your local context tree first
  2. Each configured source’s context tree
  3. Returns combined results with origin attribution
Local results get a slight relevance boost, so your own knowledge ranks first when equally relevant.

​
Commands

All source commands are available as both CLI commands and TUI slash commands.

​
source add

Add a read-only knowledge source from another ByteRover project. 
brv source add <path> [--alias <name>]
Arguments:
ArgumentDescriptionRequired
pathPath to the target project (must have .brv/config.json)Yes
Flags:
FlagDescription
--aliasCustom identifier for the source. Defaults to the target directory name
Examples: 
# Add a source with default alias (directory name)
brv source add /path/to/shared-lib
# Output: Added source "/path/to/shared-lib" as "shared-lib".

# Add with a custom alias
brv source add ../auth-service --alias auth
# Output: Added source "../auth-service" as "auth".

​
source list

Display all configured sources and their validation status. 
brv source list
Example output: 
Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /path/to/auth-service (valid)
With a broken source: 
Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /deleted/path [BROKEN - run brv source remove auth]
Broken sources (where the target’s .brv/ has been deleted) are excluded from search results but remain in the configuration until you explicitly remove them. This prevents silent data loss.

​
source remove

Remove a knowledge source reference. Only deletes the local reference — the target project is untouched. 
brv source remove <alias-or-path>
Arguments:
ArgumentDescriptionRequired
alias-or-pathThe source alias or full path to the target projectYes
Examples: 
# Remove by alias
brv source remove auth
# Output: Removed source "auth" (/path/to/auth-service).

# Remove by path
brv source remove /path/to/shared-lib
# Output: Removed source "shared-lib" (/path/to/shared-lib).

​
Search Integration

When you query a project with sources configured, results include origin information: 
brv query "JWT validation"

# Results might include:
# [local]:authentication/jwt-implementation/context.md     (your project)
# [auth]:security/token-validation/context.md              (from auth source)

​
Origin Attribution

Each result is prefixed with its origin:
PrefixMeaning
[local]From your project’s context tree
[alias]From the named source’s context tree

​
Relevance Ranking

  • Local results get a slight score boost when relevance is similar
  • Results from all sources are merged and ranked together
  • The most relevant result wins regardless of origin

​
Write Protection

Sources are strictly read-only. ByteRover enforces write guards at the tool level:
  • Attempting to curate into a shared source fails with: Cannot write to shared source — sources are read-only.
  • All mutation tools (write_file, curate) check file paths against source paths before allowing writes
  • Protection is fail-closed: if context can’t be determined, writes are blocked
This ensures you never accidentally modify another project’s knowledge base through a source reference.

​
Error Handling

ErrorCauseResolution
Target is not a ByteRover projectPath doesn’t have .brv/config.jsonInitialize the target with brv first
Cannot add self as sourceYou tried to reference your own projectAdd a different project
Duplicate sourceSame path already configuredThe source is already available — no action needed
Circular source detectedTarget already references this projectRemove one direction to break the cycle
Source marked as BROKENTarget’s .brv/ was deleted or movedRun brv source remove <alias> to clean up

​
Practical Examples

​
Platform Team Sharing Auth Patterns

# Auth team curates their patterns
cd /auth-service
brv curate "JWT tokens use RS256, expire in 24h, refresh tokens in 7d"

# Product team references auth knowledge
cd /product-api
brv source add /auth-service --alias auth

# Product devs can now query auth patterns from their own project
brv query "token expiration policy"
# Returns: [auth]:security/jwt-tokens/context.md

​
Multi-Source Architecture

cd /frontend-app
brv source add /design-system --alias design
brv source add /api-gateway --alias api
brv source add /shared-utils --alias utils

brv source list
# Knowledge Sources:
#    design → /design-system (valid)
#    api → /api-gateway (valid)
#    utils → /shared-utils (valid)

brv query "button component variants"
# Searches: local + design + api + utils context trees

​
Combined with Worktrees

Sources configured in a parent project are automatically available from all linked worktrees: 
# Parent project configures sources
cd /monorepo
brv source add /design-system --alias design

# Worktree inherits sources through the pointer
cd /monorepo/packages/web
brv query "color tokens"
# Searches: monorepo context tree + design-system source