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 |
- 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
Register a directory as a worktree of the current project.
brv worktree add [path] [--force]
| Argument | Description | Required |
|---|
path | Path to the target directory (relative or absolute) | No — defaults to current directory |
| Flag | Description |
|---|
--force | If the target already has a .brv/ directory, back it up to .brv-backup/ and replace with a pointer |
# 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.
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
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]
| Argument | Description | Required |
|---|
path | Path to the worktree to remove (relative or absolute) | No — defaults to current directory |
# 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)
