> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktrees

> Link subdirectories or sibling checkouts to a parent project for shared knowledge

## 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:

1. Creates a `.brv` **file** (not directory) in the target, pointing to the parent
2. 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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv worktree add [path] [--force]
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /worktree add [path]
    ```
  </Tab>
</Tabs>

**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:**

```bash theme={null}
# 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/).
```

<Warning>
  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.
</Warning>

### `worktree list`

Show the current worktree status and all registered worktrees.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv worktree list
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /worktree list
    ```
  </Tab>
</Tabs>

**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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv worktree remove [path]
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /worktree remove [path]
    ```
  </Tab>
</Tabs>

**Arguments:**

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

**Examples:**

```bash theme={null}
# 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
```

<Info>
  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.
</Info>

## Backup and Recovery

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

```bash theme={null}
# 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        |

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

## Integration with Other Features

### Queries and Curation

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

```bash theme={null}
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:

```bash theme={null}
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)
```