Worktrees

What Are Worktrees?

Worktrees let multiple directories share a single ByteRover context tree. Instead of each directory maintaining its own .brv/ knowledge base, child directories point back to a parent project. Curate once, query everywhere. This is especially useful for:

Monorepos — All packages share the root project’s context tree
Git worktrees — Parallel checkouts share knowledge without re-curating
Sibling directories — Related projects under a common parent

How It Works

ByteRover uses a git-style .brv file/directory duality — the same pattern Git uses for .git in worktrees:

What you see	What it means
`.brv/` directory	This is the real project — contains `config.json`, context tree, configuration
`.brv` file	This is a worktree pointer — contains a path to the parent project
No `.brv`	No project configured — `brv` will auto-initialize on first run

When you add a worktree, ByteRover:

Creates a .brv file (not directory) in the target, pointing to the parent
Registers the worktree in the parent’s .brv/worktrees/ directory

monorepo/
  .brv/                               # real project (directory)
    ├── config.json
    ├── context-tree/
    └── worktrees/
        ├── packages-api/
        │   └── link.json             # registration metadata
        └── packages-web/
            └── link.json
  packages/
    api/
      .brv                            # pointer FILE: {"projectRoot": "/monorepo"}
    web/
      .brv                            # pointer FILE: {"projectRoot": "/monorepo"}

Resolution

When you run any brv command from a worktree directory, ByteRover walks up from the current directory and stops at the first .brv it finds:

If it’s a directory — you’re in the real project
If it’s a file — follow the pointer to the parent project

This means queries, curations, and status checks from packages/api/ automatically use the monorepo’s context tree.

Commands

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

`worktree add`

brv worktree add [path] [--force]

/worktree add [path]

Arguments:

Argument	Description	Required
`path`	Path to the target directory (relative or absolute)	No — defaults to current directory

Flags:

Flag	Description
`--force`	If the target already has a `.brv/` directory, back it up to `.brv-backup/` and replace with a pointer

Examples:

# From the monorepo root, add a package
cd /monorepo
brv worktree add packages/api

# Add a sibling checkout
brv worktree add ../sibling-checkout

# Auto-detect: from inside a subdirectory, add yourself
cd /monorepo/packages/api
brv worktree add

# Force-add when target already has its own .brv/ directory
brv worktree add packages/api --force
# Output: Added worktree ".../packages/api" (existing .brv/ backed up to .brv-backup/).

Without --force, the command will fail if the target already has a .brv/ directory. Use --force to safely migrate — the existing directory is backed up and restored on removal.

`worktree list`

Show the current worktree status and all registered worktrees.

brv worktree list

/worktree list

Example output from a linked worktree:

Worktree: /monorepo/packages/api
Linked to: /monorepo

Registered worktrees:
   packages-api → /monorepo/packages/api
   packages-web → /monorepo/packages/web

Example output from the project root:

Project: /monorepo

Registered worktrees:
   packages-api → /monorepo/packages/api
   packages-web → /monorepo/packages/web

`worktree remove`

Remove a worktree registration and delete its .brv pointer file.

brv worktree remove [path]

/worktree remove [path]

Arguments:

Argument	Description	Required
`path`	Path to the worktree to remove (relative or absolute)	No — defaults to current directory

Examples:

# Remove from the parent project
cd /monorepo
brv worktree remove packages/api

# Remove from inside the worktree itself
cd /monorepo/packages/api
brv worktree remove

If the worktree was added with --force (and a .brv-backup/ exists), the backup is automatically restored as .brv/ on removal. Your original context tree is preserved.

Backup and Recovery

The --force flag enables safe migration of directories that already have their own .brv/ setup:

# Before: packages/api has its own curated knowledge
ls packages/api/.brv/
# config.json  context-tree/

# Add as worktree with --force
brv worktree add packages/api --force
# Existing .brv/ backed up to .brv-backup/

ls packages/api/
# .brv              (pointer file)
# .brv-backup/      (original directory, preserved)

# Later, if you remove the worktree:
brv worktree remove packages/api
# .brv-backup/ restored as .brv/

ls packages/api/.brv/
# config.json  context-tree/   (original content restored)

Error Handling

Error	Cause	Resolution
Cannot add project root as its own worktree	You tried to add the project to itself	Add a subdirectory or external path instead
Target directory does not exist	The specified path doesn’t exist	Check the path and try again
Target already has `.brv/` directory	Target has its own project setup	Use `--force` to migrate, or remove the existing `.brv/` first
Already linked to a different parent	Target’s `.brv` file points elsewhere	Run `brv worktree remove` in the target first
Worktree pointer broken	Parent project’s `.brv/config.json` was deleted	Run `brv worktree remove` to clean up the stale pointer

Broken pointer errors include recovery instructions. If you see one, follow the suggested command to clean up.

Integration with Other Features

Queries and Curation

From a linked worktree, all queries and curations operate on the parent project’s context tree:

cd /monorepo/packages/api
brv query "auth patterns"         # searches monorepo's context tree
brv curate "API rate limiting"    # curates to monorepo's context tree

Sources

Sources configured in the parent project are automatically available from all worktrees:

cd /monorepo
brv source add /path/to/design-system --alias design

cd /monorepo/packages/api
brv query "button component"
# Searches: monorepo context tree + design-system source

Status

brv status shows worktree information when you’re in a linked directory:

Worktree: /monorepo/packages/api (linked)

Getting Started

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

What Are Worktrees?

How It Works

Resolution

Commands

`worktree add`

`worktree list`

`worktree remove`

Backup and Recovery

Error Handling

Integration with Other Features

Queries and Curation

Sources

Status

​What Are Worktrees?

​How It Works

​Resolution

​Commands

​worktree add

​worktree list

​worktree remove

​Backup and Recovery

​Error Handling

​Integration with Other Features

​Queries and Curation

​Sources

​Status

What Are Worktrees?

How It Works

Resolution

Commands

`worktree add`

`worktree list`

`worktree remove`

Backup and Recovery

Error Handling

Integration with Other Features

Queries and Curation

Sources

Status