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

# Team Context Sync

> Collaborate with your team by syncing context to the cloud using Git-Semantic version control

Team sync uses **Git-Semantic version control** (`brv vc`) to push and pull commits between your local context tree and ByteRover cloud. Your core workflow (curate and query) works fully offline — cloud sync is optional and designed for team collaboration.

<Note>
  Cloud sync requires authentication. Run `/login` or `brv login` to connect your cloud account. See [Local vs Cloud](/local-vs-cloud) for full setup instructions.
</Note>

## When You Need Push/Pull

| Use case               | Why                                                           |
| ---------------------- | ------------------------------------------------------------- |
| **Team collaboration** | Share curated knowledge so teammates query the same context   |
| **Multi-machine sync** | Push from your laptop, pull on a server or CI environment     |
| **Backup**             | Persist your context tree outside the local `.brv/` directory |

If you are working solo on a single machine, you do not need push or pull. Everything curated locally is immediately queryable.

## Setup: Connect to a remote space

Before pushing or pulling, connect your local space to a remote:

<Tabs>
  <Tab title="New space (local to cloud)">
    <Steps>
      <Step title="Initialize version control">
        ```bash theme={null}
        brv vc init
        brv vc config user.name "Your Name"
        brv vc config user.email "you@example.com"
        ```
      </Step>

      <Step title="Add a remote">
        ```bash theme={null}
        brv vc remote add origin https://byterover.dev/<team>/<space>.git
        ```

        Find the URL on the space's page in the [ByteRover Dashboard](https://app.byterover.dev).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Existing space (cloud to local)">
    Clone a space that already exists on ByteRover cloud:

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        brv vc clone https://byterover.dev/<team>/<space>.git
        brv vc config user.name "Your Name"
        brv vc config user.email "you@example.com"
        ```
      </Tab>

      <Tab title="TUI">
        ```
        /vc clone https://byterover.dev/<team>/<space>.git
        /vc config user.name "Your Name"
        /vc config user.email "you@example.com"
        ```

        Or omit the URL to browse your team's spaces with an interactive picker:

        ```
        /vc clone
        ```
      </Tab>
    </Tabs>

    Cloning downloads the full context tree with its complete commit history. The remote is already configured.
  </Tab>
</Tabs>

## Step 1: Stage and commit

After curating context, stage your changes and create a commit:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc add .
    brv vc commit -m "add rate limiting context"
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc add .
    /vc commit -m "add rate limiting context"
    ```
  </Tab>
</Tabs>

## Step 2: Push to remote

Push your commits to ByteRover cloud:

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    brv vc push
    ```

    On the first push, set upstream tracking:

    ```bash theme={null}
    brv vc push -u origin main
    ```
  </Tab>

  <Tab title="TUI">
    ```
    /vc push
    ```

    On the first push, set upstream tracking:

    ```
    /vc push -u origin main
    ```
  </Tab>
</Tabs>

Your context is now available to your team.

## Step 3: Pull team context

When teammates push context, pull their changes into your local context tree:

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

  <Tab title="TUI">
    ```
    /vc pull
    ```
  </Tab>
</Tabs>

Now you have access to your team's collective knowledge.

## Complete workflow cycle

The local-first flow is: **curate locally → commit → (optionally) push/pull for teams**. Here is how it all fits together.

Prompt your coding agent to implement a task, mentioning ByteRover:

```
> Add a rate limiter to the API endpoints. Use ByteRover to check existing patterns first.
```

Your coding agent will:

1. **Query existing context** in the local context tree to understand your codebase patterns:

```bash theme={null}
brv query "How are API endpoints structured? Are there any rate limiting patterns?"
```

2. **Implement the task** using the retrieved context as guidance.

3. **Curate new context** to capture what it learned:

```bash theme={null}
brv curate "Rate limiting uses sliding window algorithm at 100 req/min per user. Implemented in rateLimiter.ts middleware." -f src/middleware/rateLimiter.ts
```

4. **Stage and commit** the new context:

```bash theme={null}
brv vc add .
brv vc commit -m "add rate limiting patterns"
```

At this point your new context is committed locally and queryable. The following steps are optional and only needed for team collaboration:

5. **(Optional) Push to remote** to share the new context with your team:

```bash theme={null}
brv vc push
```

6. **(Optional) Pull team updates** to get context that teammates have added:

```bash theme={null}
brv vc pull
```

This creates a feedback loop where your coding agent learns from past decisions and contributes new knowledge back to your team's shared memory.

## Handling conflicts

If teammates have pushed changes that conflict with yours, `brv vc pull` will report a merge conflict. Resolve it using the merge workflow:

```bash theme={null}
# Edit the conflicting files to resolve markers (<<<<<<<, =======, >>>>>>>)

# Stage the resolved files and complete the merge
brv vc add .
brv vc merge --continue -m "resolve merge conflicts"
```

For more details, see [Branching & Merging](/git-semantic/branching-and-merging).

## Next steps

<CardGroup cols={3}>
  <Card title="Local vs Cloud" icon="cloud" href="/local-vs-cloud">
    Full breakdown of local and cloud commands with setup instructions
  </Card>

  <Card title="Remote Sync" icon="cloud" href="/git-semantic/remote-sync">
    Full push, pull, fetch, and remote management reference
  </Card>

  <Card title="Curate Context" icon="sparkles" href="/common-workflows/curate-context">
    Learn best practices for adding context
  </Card>
</CardGroup>