# Claude Code
Source: https://docs.byterover.dev/v4/agents/claude-code
Connect Claude Code on a VPS or terminal session to ByteRover V4 with authentication before onboarding.
Use the published ByteRover skill to give Claude Code access to persistent project memory from a VPS, remote shell, or local terminal.
## Before you start
* Install and authenticate Claude Code in the terminal where you will work.
* Open the project folder in the same shell where Claude Code runs.
## Optional step 0: Remove old V3 CLI, connectors, and integrations
If this environment still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
## Install the ByteRover skill
Run this in the terminal environment where Claude Code runs:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Run the command in the same environment where Claude Code runs.
## Restart Claude Code
Stop the current Claude Code session, then start a new one in the project:
```bash theme={null}
cd path/to/your/project
claude
```
Agents load installed skills when a new session starts.
## Authenticate with ByteRover
Prompt Claude Code:
```text theme={null}
Authenticate with ByteRover.
```
Claude Code may print a browser URL and ask you to approve the connection.
1. Open the URL in your browser.
2. Approve the request before the code expires.
3. Return to the terminal.
4. Type:
```text theme={null}
approved
```
## Onboard with ByteRover
Prompt Claude Code:
```text theme={null}
onboard with ByteRover
```
Claude Code checks whether the project is linked to a ByteRover space.
## If Claude Code needs a space
Open ByteRover Desktop, create or select the space for this project, then prompt Claude Code again:
```text theme={null}
onboard with ByteRover
```
## Verify
Ask Claude Code to check ByteRover before starting work:
```text theme={null}
query ByteRover for this project
```
After setup, Claude Code should query memory before non-trivial work and record useful project knowledge when work is complete.
## Next steps
Learn in depth how the agent retrieves project memory.
Learn in depth how the agent saves durable knowledge.
Manage where this project's memory lives.
# Codex CLI
Source: https://docs.byterover.dev/v4/agents/codex-cli
Connect Codex CLI on a VPS or remote development machine to ByteRover V4 with authentication before onboarding.
Use the published ByteRover skill to give Codex CLI access to persistent project memory on a VPS or any terminal environment.
## Before you start
* Install and authenticate Codex CLI on the VPS.
* Open the project folder in the same shell where Codex CLI runs.
## Optional step 0: Remove old V3 CLI, connectors, and integrations
If this VPS still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
## Install the ByteRover skill
Run this on the VPS:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Run the command in the same environment where Codex CLI runs.
## Restart Codex CLI
Stop the current Codex CLI session, then start a new one in the project:
```bash theme={null}
cd path/to/your/project
codex
```
Agents load installed skills when a new session starts.
## Authenticate with ByteRover
Prompt Codex CLI:
```text theme={null}
Authenticate with ByteRover.
```
Codex CLI may print a browser URL and ask you to approve the connection.
1. Open the URL in your browser.
2. Approve the request before the code expires.
3. Return to the VPS terminal.
4. Type:
```text theme={null}
approved
```
## Onboard with ByteRover
Prompt Codex CLI:
```text theme={null}
onboard with ByteRover
```
Codex CLI checks whether the project is linked to a ByteRover space.
## If Codex CLI needs a space
Open ByteRover Desktop, create or select the space for this project, then prompt Codex CLI again:
```text theme={null}
onboard with ByteRover
```
## Verify
Ask Codex CLI to check ByteRover before starting work:
```text theme={null}
query ByteRover for this project
```
After setup, Codex CLI should query memory before non-trivial work and record useful project knowledge when work is complete.
## Next steps
Learn in depth how the agent retrieves project memory.
Learn in depth how the agent saves durable knowledge.
Manage where this project's memory lives.
# Hermes
Source: https://docs.byterover.dev/v4/agents/hermes
Connect Hermes to ByteRover V4 with the published skill, authentication, and onboarding prompt.
Use the published ByteRover skill to give Hermes access to persistent project memory.
## Setup
If this machine still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
Run:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Fully quit and reopen Hermes so it can load the installed ByteRover skill.
Prompt Hermes:
```text theme={null}
Authenticate with ByteRover.
```
Open the URL Hermes prints, approve the request in your browser, then return to Hermes and type:
```text theme={null}
approved
```
Prompt Hermes:
```text theme={null}
onboard with ByteRover
```
## Authentication URL flow
Hermes may ask you to finish account linking in the browser.
Follow the URL flow exactly as Hermes prints it before you start onboarding:
1. Tell Hermes to start the authentication flow.
2. Open the URL that Hermes prints in your browser.
3. Confirm the browser page before the code expires.
4. Return to Hermes and type:
```text theme={null}
approved
```
Use the URL and code printed by your Hermes session. Do not copy values from the example image.
## If Hermes needs a space
During onboarding, Hermes may tell you that ByteRover is not configured for the current workspace.
When that happens:
1. Open ByteRover Desktop.
2. Create or select the space for this project.
3. Return to Hermes.
4. Prompt Hermes again:
```text theme={null}
onboard with ByteRover
```
Hermes checks the current project again and continues setup.
## Verify
After onboarding, ask Hermes to check ByteRover before starting work:
```text theme={null}
query ByteRover for this project
```
Hermes should use ByteRover automatically after setup: query before non-trivial work and record useful knowledge when the work is complete.
## Next steps
Learn in depth how the agent retrieves project memory.
Learn in depth how the agent saves durable knowledge.
Manage where this project's memory lives.
# V3 to V4 VPS migration
Source: https://docs.byterover.dev/v4/agents/migrate-v3-to-v4
Move ByteRover V3 memory on a VPS into ByteRover V4 spaces.
Use this when your VPS still has ByteRover V3 memory in `.brv/context-tree/` and you want to move it into ByteRover V4.
## Optional step 0: Remove old V3 CLI, connectors, and integrations
If this VPS still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes the old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not replace the migration step for V3 memory data.
## Install ByteRover skill
Run this on the VPS, in the same environment where your agent runs:
```bash theme={null}
npx skills add campfirein/skills
```
Restart the agent after installation.
The VPS needs Node.js 20 or newer. Node.js includes `npm` and `npx`.
## Authenticate with ByteRover
Ask your agent:
```text theme={null}
auth with ByteRover
```
The agent starts ByteRover authentication and prints a browser URL. Open the URL, approve the request, then return to the VPS terminal and type `approved` when the agent asks.
Authentication must finish before migration starts.
## Migrate data from V3 to V4
Ask your agent:
```text theme={null}
migrate data from v3 to v4
```
The agent checks the VPS for V3 projects, previews what will be migrated, then moves the V3 memory into V4 spaces.
Each V3 project becomes a V4 space. The old markdown memory is converted into V4 topics.
## Verify the migration
Ask your agent:
```text theme={null}
verify v3 to v4 migration
```
The agent checks the migrated spaces and topic counts. After that, open ByteRover Desktop and confirm the new V4 spaces are available.
## Cleanup old V3 files
Only cleanup after the V4 spaces are verified.
Ask your agent:
```text theme={null}
cleanup v3 files after migration
```
The agent backs up the whole V3 `.brv/` folder, then removes the original `.brv/` from the project.
By default, backups are stored in your Documents folder:
```text theme={null}
~/Documents/ByteRover_Backups//brv/
```
The cleanup command also writes a manifest at the backup root:
```text theme={null}
~/Documents/ByteRover_Backups/manifest.json
```
If the agent uses a custom backup parent, ByteRover still creates a `ByteRover_Backups` folder inside it:
```text theme={null}
/ByteRover_Backups//brv/
```
To restore old V3 files, copy the backed up `brv/` folder back to the project as `.brv/`.
## Next steps
Onboard the migrated project and start using V4 memory.
Retrieve migrated project memory before work starts.
Review the full V4 first-run setup.
# OpenClaw
Source: https://docs.byterover.dev/v4/agents/openclaw
Connect OpenClaw to ByteRover V4 with the setup script, context engine, authentication, and onboarding prompt.
Use the OpenClaw V4 setup script to install the ByteRover skill and configure ByteRover as the OpenClaw context engine.
## Setup
If this machine still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
Run the OpenClaw V4 setup script:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh
```
This installs the published ByteRover skill and configures the latest ByteRover OpenClaw context engine.
Fully quit and reopen OpenClaw so it can load the installed ByteRover skill and context engine.
Prompt OpenClaw:
```text theme={null}
Authenticate with ByteRover.
```
Open the URL OpenClaw prints, approve the request in your browser, then return to OpenClaw and type:
```text theme={null}
approved
```
Prompt OpenClaw:
```text theme={null}
onboard with ByteRover
```
## Authentication URL flow
OpenClaw may ask you to finish account linking in the browser.
Follow the URL flow exactly as OpenClaw prints it before you start onboarding:
1. Tell OpenClaw to start the authentication flow.
2. Open the URL that OpenClaw prints in your browser.
3. Confirm the browser page before the code expires.
4. Return to OpenClaw and type:
```text theme={null}
approved
```
Use the URL and code printed by your OpenClaw session. Do not copy values from the example image.
## If OpenClaw needs a space
During onboarding, OpenClaw may tell you that ByteRover is not configured for the current workspace.
When that happens:
1. Open ByteRover Desktop.
2. Create or select the space for this project.
3. Return to OpenClaw.
4. Prompt OpenClaw again:
```text theme={null}
onboard with ByteRover
```
OpenClaw checks the current project again and continues setup.
## Verify
After onboarding, ask OpenClaw to check ByteRover before starting work:
```text theme={null}
query ByteRover for this project
```
OpenClaw should use ByteRover automatically after setup: query before non-trivial work and record useful knowledge when the work is complete.
## Cleanup: uninstall the context engine
If you want OpenClaw to stop using the ByteRover context engine, run the same setup script with the uninstall flag:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh -s -- --uninstall-context-engine
```
This resets OpenClaw to its legacy context engine and removes the ByteRover OpenClaw plugin. It does not delete your ByteRover spaces or saved memory.
## Next steps
Learn in depth how the agent retrieves project memory.
Learn in depth how the agent saves durable knowledge.
Manage where this project's memory lives.
# OpenCode CLI
Source: https://docs.byterover.dev/v4/agents/opencode-cli
Connect OpenCode CLI on a VPS or terminal session to ByteRover V4 with authentication before onboarding.
Use the published ByteRover skill to give OpenCode CLI access to persistent project memory from a VPS, remote shell, or local terminal.
## Before you start
* Install and authenticate OpenCode CLI in the terminal where you will work.
* Open the project folder in the same shell where OpenCode CLI runs.
## Optional step 0: Remove old V3 CLI, connectors, and integrations
If this environment still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
## Install the ByteRover skill
Run this in the terminal environment where OpenCode CLI runs:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Run the command in the same environment where OpenCode CLI runs.
## Restart OpenCode CLI
Stop the current OpenCode session, then start a new one in the project:
```bash theme={null}
cd path/to/your/project
opencode
```
Agents load installed skills when a new session starts.
## Authenticate with ByteRover
Prompt OpenCode CLI:
```text theme={null}
Authenticate with ByteRover.
```
OpenCode CLI may print a browser URL and ask you to approve the connection.
1. Open the URL in your browser.
2. Approve the request before the code expires.
3. Return to the terminal.
4. Type:
```text theme={null}
approved
```
## Onboard with ByteRover
Prompt OpenCode CLI:
```text theme={null}
onboard with ByteRover
```
OpenCode CLI checks whether the project is linked to a ByteRover space.
## If OpenCode CLI needs a space
Open ByteRover Desktop, create or select the space for this project, then prompt OpenCode CLI again:
```text theme={null}
onboard with ByteRover
```
## Verify
Ask OpenCode CLI to check ByteRover before starting work:
```text theme={null}
query ByteRover for this project
```
After setup, OpenCode CLI should query memory before non-trivial work and record useful project knowledge when work is complete.
## Next steps
Learn in depth how the agent retrieves project memory.
Learn in depth how the agent saves durable knowledge.
Manage where this project's memory lives.
# Agents
Source: https://docs.byterover.dev/v4/agents/overview
Connect OpenClaw, Hermes, and VPS CLI agents to ByteRover V4 with the published skill, authentication, and onboarding prompt.
ByteRover V4 connects agents through the published ByteRover skill. Install the skill in the same environment where the agent runs, restart the agent, authenticate ByteRover, then start onboarding from inside your project.
OpenClaw also supports a V4 setup script that installs the skill and configures the ByteRover context engine.
## Setup flow
If this environment still has the old V3 CLI, connectors, OpenClaw integration, or Hermes memory provider installed, remove them before setting up the V4 skill:
```bash theme={null}
curl -fsSL https://www.byterover.dev/uninstall-v3.sh | sh
```
This removes old V3 command-line tools and connectors. It also removes the old OpenClaw integration and Hermes memory provider when they are detected. It does not migrate V3 memory data.
Requires Node.js 20 or newer. Node.js includes npm and npx.
For OpenClaw, run the setup script:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh
```
This installs the ByteRover skill and configures the latest ByteRover OpenClaw context engine.
To clean up the OpenClaw context engine later, run the same script with the uninstall flag:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh -s -- --uninstall-context-engine
```
For other agents, install the published ByteRover skill:
```bash theme={null}
npx skills add campfirein/skills
```
This installs the published ByteRover skill bundle from `campfirein/skills`.
Fully quit and reopen the agent so it can load the installed ByteRover skill.
```text theme={null}
Authenticate with ByteRover.
```
Open the URL the agent prints, approve the request in your browser, then return to the agent and type `approved`.
```text theme={null}
onboard with ByteRover
```
The agent links the project to the right space and begins using durable memory after onboarding.
## Supported agents
Choose the agent you want to connect.
Install the skill and context engine, restart OpenClaw, authenticate, and start onboarding.
Install the skill, restart Hermes, authenticate, and start onboarding.
Use ByteRover from Codex CLI on a VPS or remote development machine.
Use ByteRover from Claude Code in a terminal session.
Use ByteRover from OpenCode CLI on a VPS or local terminal.
Move self-managed V3 project memory on a VPS into V4 spaces.
## VPS notes
When the agent runs on a VPS, install the ByteRover skill on the VPS, not only on your laptop. The agent reads skills from its own environment.
Authenticate before onboarding. If the agent prints a sign-in URL, open that URL in your browser. After you approve it, return to the VPS terminal and type:
```text theme={null}
approved
```
If the agent cannot find a space for the project, open ByteRover Desktop, create or select the right space, then prompt the agent again:
```text theme={null}
onboard with ByteRover
```
If the VPS already has V3 project memory, migrate it before relying on the project in V4:
Detect V3 projects, preview the migration, create V4 spaces, verify the result, then back up and remove old V3 files.
# Connect Agent
Source: https://docs.byterover.dev/v4/desktop/connect-agent
Connect ByteRover Desktop to supported coding agents.
Connect your coding agent so it can use the ByteRover skill from inside your project.
## Before you start
* Install and open ByteRover Desktop.
* Sign in to your ByteRover account.
* Be ready to restart the coding agent after connecting it.
## Supported agents
Desktop can connect ByteRover to these coding agents:
* Claude Code
* Claude Desktop
* Codex
* OpenCode
* OpenClaw
* Hermes
* Devin (Windsurf)
* Cursor
* Gemini CLI
* GitHub Copilot
Some agents share the same global skills folder. Desktop may show them together as **Compatible agents**. Connecting that bundle installs ByteRover once for every agent that reads from the shared folder.
## Open the agent connection screen
During first setup, Desktop opens **Connect your agents** after sign-in.
After onboarding, open the same controls from Desktop:
* select **Add agent** if no agent is connected yet
* select **Manage agents** if you already connected one or more agents
## Connect your agent
Find the agent you use for development, then follow the action shown in Desktop.
| Desktop action | Meaning | What to do |
| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Connect** | Desktop can install the ByteRover skill for this agent. | Select **Connect**. |
| **Connected** | The ByteRover skill is already installed. | Restart the agent if you just connected it, then onboard with ByteRover. Use **Disconnect** if you need to remove the skill. |
| **Update** | The agent has an older ByteRover skill installed. | Select **Update** to reinstall the latest bundled skill. |
| **Install Guide** | This agent requires manual setup. | Open the guide and follow the steps shown in Desktop. |
Most agents are connected directly from Desktop. Claude Desktop uses an install guide because its skill upload is manual.
When you are in first setup, select **Continue** after the agent connection step.
Desktop **Connect** and **Update** reinstall the bundled ByteRover skill over any existing Desktop-managed copy.
## Update or disconnect
Use **Manage agents** after the first setup.
* Select **Update** when Desktop shows that an installed skill is outdated.
* Select **Disconnect** when you want Desktop to remove the ByteRover skill for that agent.
* Reconnect the agent later with **Connect**.
Disconnecting removes the skill from that agent's install location. It does not delete your spaces or saved memory.
## Use manual install when needed
For OpenClaw manual setup, use the V4 setup script. It installs the published ByteRover skill and configures the ByteRover OpenClaw context engine:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh
```
To clean up the OpenClaw context engine later, run the same script with the uninstall flag:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh -s -- --uninstall-context-engine
```
For VPS CLI agents or other manual skill flows, install the published ByteRover skill from the terminal in the environment where the agent runs:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Restart the agent after the command finishes.
The ByteRover skill loads when the agent starts. If the agent was already open, restart it before you try onboarding.
## Claude Desktop video guide
Claude Desktop uses a manual upload flow. When Desktop shows **Install Guide** for Claude Desktop, follow the guide and use this video as the visual reference.
The Claude Desktop flow is:
1. Select **Save to Downloads** in ByteRover Desktop.
2. Open Claude Desktop.
3. Go to **Customize** > **Skills** > **+** > **Create skill** > **Upload**.
4. Upload the `byterover-skill-*.zip` file from Downloads.
5. Return to ByteRover Desktop and wait for Claude Desktop to show as connected.
## Onboard with ByteRover
Open the connected agent in your project and prompt:
```text theme={null}
onboard with ByteRover
```
The agent will check the current project, connect to the right ByteRover space, and tell you what to do if a space still needs to be created in Desktop.
## Next steps
Invite teammates and manage team roles.
Control where project memory lives and who can access it.
# Space
Source: https://docs.byterover.dev/v4/desktop/space
Organize personal and team memory in ByteRover spaces.
Spaces are the memory boundary in ByteRover. Your agent queries and records memory inside the active space for the project.
Use spaces to keep personal work, team work, and shared project memory separated.
## Space levels
ByteRover Desktop organizes spaces into three levels.
* **Shared with me** is global. It shows spaces shared to you from another person or another team. These can come from a direct invite or from a team-wide share.
* **Private** belongs to the selected team view. These are personal spaces under the selected team. They are private by default, but you can share them with people inside or outside the team.
* **Team space** belongs to the selected team view. These spaces are visible to the selected team, and you can still share them with people outside the team when the project needs cross-team access.
## Choose the right level
Before starting an agent session, open the space that matches the work you are doing.
* Use **Private** for experiments, personal notes, or work that is not ready for the team.
* Use **Team space** when teammates should reuse the same project memory.
* Use **Shared with me** when another person or team has shared memory with you.
The connected agent will query and record against the selected space.
## Create a space
In the sidebar, select the `+` button beside **Private** or **Team space**.
When creating a space, choose its visibility:
| Visibility | Use it when |
| --------------- | --------------------------------------------------------------- |
| **Private** | Only you should see the space first. You can share it later. |
| **Team shared** | Everyone in the selected team should be able to view the space. |
Only Owners and Admins can create team spaces. Members can use spaces they have access to, but cannot create a new team-wide space.
## Share with specific people
Open the space, select **Share**, then add a person by email.
Choose a role before you add them:
| Role in Share dialog | What it allows |
| -------------------- | --------------------------------------------------------------- |
| **Owner** | Add contexts, manage members, share links, and manage settings. |
| **Admin** | Add contexts, manage members, and share links. |
| **Editor** | Add contexts and view memory. |
| **Viewer** | View memory only. |
Use **Viewer** when someone only needs to read memory. Use **Editor** when their agent should record new context into the space.
You can share a private space or a team space with people outside the selected team. The invited person will see it under **Shared with me**.
## Set general access
In the Share dialog, use **General access** to choose who can open the space.
| Option | Use it when |
| --------------- | ------------------------------------------------------------- |
| **Restricted** | Only people you added directly should have access. |
| **Team access** | Everyone in the owning team should be able to open the space. |
When you switch a space from restricted to team access, Desktop shows how many teammates will gain access.
You can also move a space between **Private** and **Team space** from the sidebar. Drag the space into the other section to change who can see it.
## Review shared spaces
Spaces shared with you appear in **Shared with me**.
Shared spaces can come from:
* a direct share to your email
* a team-wide share from another team
If you were added directly, you can leave the shared space from the row menu. If access comes from a team-wide share, access is controlled by the team membership instead.
If the space is view-only, your agent can query memory but cannot record new context.
## Manage a space
Use the row menu on a space to manage it.
| Action | What it does |
| ------------------ | -------------------------------------------------------------------------------- |
| **Rename** | Changes the space name. |
| **Share settings** | Opens the Share dialog for people, roles, and general access. |
| **Delete** | Deletes the space when your role allows it. The default space cannot be deleted. |
View-only spaces show a view-only marker. Your agent is read-only in those spaces too.
## Search topics
Use the Desktop search box or `Cmd K` / `Ctrl K` to search topic titles across visible spaces.
Search results are grouped by:
* Private spaces
* Team spaces
* Shared with me
Open a result to jump directly to that topic inside its space.
## Next steps
Connect a project folder to the right space from your agent.
Retrieve memory from the selected space before work starts.
# Team
Source: https://docs.byterover.dev/v4/desktop/team
Invite teammates and manage access to shared ByteRover spaces.
A team controls who can use shared ByteRover memory, who can manage the workspace, and who can create or share team spaces.
Use team settings when you need to switch teams, invite teammates, change roles, manage billing, or review pending invitations.
## Team surfaces
ByteRover Desktop has four team surfaces.
| Surface | Use it for |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| **Team selector** | Switch the active team, create a new team, or open team management. |
| **General** | Edit the team name and logo, review the owner, leave the team, or delete the team when allowed. |
| **Members** | Invite members, change roles, remove members, resend invites, and revoke pending invites. |
| **Billing** | View the plan, manage seats, open the billing portal, or update payment. Billing is Owner-only. |
## Select the team
Open ByteRover Desktop and choose the team from the team selector.
The selected team controls which **Private** and **Team space** sections you see in the sidebar. When you switch teams, Desktop switches the visible spaces too.
## Open Members
Go to **Members** to manage the roster.
Use search when the roster is long.
## Invite a teammate
Select **Invite member**, enter the teammate's email address, then choose a role.
You can assign these roles during invite:
* **Viewer** - read-only access to team memory.
* **Member** - can add and view memory.
* **Admin** - can manage members and memory.
Owner is not a normal invite role. Ownership is transferred separately by an existing Owner.
## Manage members
From the Members page, Owners and Admins can:
* change a member's role
* remove a member from the team
* resend or revoke pending invitations
* review how many seats are still available
Only Owners can transfer ownership.
## Manage team settings
Open **General** when you need to manage the team itself.
| Setting | Who can use it |
| ----------- | ---------------------------------------- |
| Team logo | Owner or Admin |
| Team name | Owner or Admin |
| Owner row | Everyone can view |
| Leave team | Admin, Member, or Viewer |
| Delete team | Owner only, and not for the default team |
Leaving a team removes your access to that team's spaces and memory. Deleting a team permanently deletes the workspace, its spaces, and memberships.
## Manage billing
Open **Billing** to review the current plan and seats.
Billing is Owner-only. If someone else owns the team, ask that Owner to manage the plan or payment method.
Owners can:
* open the billing portal
* manage seats on a paid plan
* resume a scheduled cancellation
* update payment when a payment is past due
* start checkout for a paid plan
## Role permissions
Use the smallest role that gives the teammate what they need.
| Role | Permission |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Full control of the team, billing, and every space inside it. Transferring ownership is itself a privileged action. |
| **Admin** | Runs the team day to day. Admin is identical to Owner except for billing access and the two team-destroying actions: delete team and transfer ownership. |
| **Member** | Uses the team's spaces: reads memories and writes new contexts. Cannot manage members, billing, or sharing. |
| **Viewer** | Read-only seat. Can see the team and read space contents; cannot write or share. |
Review permissions when a teammate changes projects or no longer needs access to a shared memory space.
## Team spaces
Team spaces make memory reusable across the group.
Team roles affect space behavior:
* Owners and Admins can create team spaces.
* Members can read and write memory in spaces they can access.
* Viewers can read memory only.
* Billing access stays Owner-only, even for Admins.
When a teammate works inside a team space, their connected agent can query and record according to that teammate's team role and the space access you grant.
## Next steps
Manage access for a specific memory space.
Start using shared memory from inside your agent.
# Quick start
Source: https://docs.byterover.dev/v4/getting-started
Install ByteRover Desktop, sign in, connect your agent, and onboard with ByteRover.
Use this guide to set up ByteRover V4 for one coding agent.
ByteRover V4 has two parts you will use together:
* **ByteRover Desktop** manages sign-in, onboarding, spaces, teams, sharing, sync status, and connected agents.
* **ByteRover skill** runs inside your coding agent so the agent can query and record project memory.
## Step 1: Desktop installation
Download and install ByteRover Desktop for your computer.
[Download ByteRover Desktop](https://byterover.dev/download)
Open ByteRover Desktop after installation. On a first run, Desktop shows the ByteRover welcome screen. Select **Get started** to continue setup.
ByteRover Desktop also registers the `byterover://` protocol. This lets browser actions return to the desktop app for sign-in, invitations, billing, and topic links.
## Step 2: Sign in through the browser
Choose **Continue with Google** or **Continue with GitHub** in ByteRover Desktop.
Desktop opens the sign-in flow in your browser. Complete the provider sign-in there, then approve the prompt to return to ByteRover Desktop if your browser asks.
If Desktop finds an existing ByteRover CLI session, it may also show **Continue as** your detected account. Use that option only when it is the account you want to use for V4.
V4 requires sign-in before you can use Desktop. After sign-in, Desktop continues onboarding and loads your spaces, teams, and connected agents.
## Step 3: Connect your agent
On first setup, Desktop opens the agent connection step. Connect the coding agent you use for development.
Desktop shows each supported agent with one of these actions:
* **Connect** installs the ByteRover skill for that agent.
* **Connected** means the skill is already installed.
* **Update** reinstalls the latest bundled skill when Desktop finds an older copy.
* **Install Guide** means the agent needs a manual setup flow.
After you connect at least one agent, select **Continue** in Desktop.
For OpenClaw, use the V4 setup script. It installs the ByteRover skill and configures the ByteRover OpenClaw context engine:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh
```
To clean up the OpenClaw context engine later, run the same script with the uninstall flag:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh -s -- --uninstall-context-engine
```
For VPS CLI agents or other manual skill installs, run the install command in the same environment where the agent runs:
Requires Node.js 20 or newer. Node.js includes npm and npx.
```bash theme={null}
npx skills add campfirein/skills
```
Restart the agent after connecting it. Agents load the ByteRover skill at startup.
## Step 4: Onboard with ByteRover
Open your coding agent in the project you want to work on. Use the onboarding prompt shown by Desktop, or send:
```text theme={null}
onboard with ByteRover
```
If Desktop copied **Start ByteRover onboarding** for you, paste that prompt. It starts the same onboarding flow.
The agent will check whether ByteRover is ready for that project.
* If a space is already available, the agent connects to it and confirms setup.
* If no space is available, open ByteRover Desktop, create or select a space for the project, then run the prompt again.
* If the agent needs authentication, it will give you a browser URL. Open the URL, approve the request, then return to the agent and say `approved`.
After onboarding, ask the agent to check ByteRover before doing real work:
```text theme={null}
query ByteRover for this project
```
The agent should use ByteRover automatically after setup:
* query project memory before non-trivial work
* record useful project knowledge after work is complete
## Next steps
* [Connect Agent](/v4/desktop/connect-agent) - manage agent connections from Desktop.
* [Team](/v4/desktop/team) - invite teammates and manage team roles.
* [Space](/v4/desktop/space) - control where project memory lives and who can access it.
* [Agents](/v4/agents/overview) - connect OpenClaw, Hermes, Codex CLI, Claude Code, and OpenCode CLI.
* [Bind](/v4/skill/bind) - connect a project folder to the right ByteRover space.
* [Query](/v4/skill/query) - retrieve project memory before work starts.
* [Record](/v4/skill/record) - save durable project knowledge after work is complete.
* [Dream](/v4/skill/dream) - review cleanup and consolidation proposals for saved memory.
* [Auth](/v4/skill/auth) - approve skill authentication when an agent asks for it.
# Overview
Source: https://docs.byterover.dev/v4/overview
ByteRover V4 gives coding agents durable project memory through Desktop, spaces, teams, and the ByteRover skill.
ByteRover V4 helps your coding agents remember project decisions, team context, and useful implementation details across sessions. Desktop manages the workspace. The ByteRover skill runs inside your agent and uses the selected space as durable memory.
## Get started in minutes
Download ByteRover Desktop, open the app, and start setup.
[Download ByteRover Desktop](https://byterover.dev/download)
Sign in with Google or GitHub. Desktop uses your account to load teams, spaces, invitations, and connected agents.
Use Desktop to connect a local coding agent, or install the ByteRover skill manually on a VPS:
Requires Node.js 20 or newer. Node.js includes npm and npx.
For OpenClaw, use the V4 setup script placeholder to install the skill and context engine:
```bash theme={null}
curl -fsSL https://byterover.dev/openclaw-setup-v4.sh | sh
```
For other agents, install the published ByteRover skill:
```bash theme={null}
npx skills add campfirein/skills
```
To clean up the OpenClaw context engine later, run the setup script with `--uninstall-context-engine`.
Open the agent in your project and prompt:
```text theme={null}
onboard with ByteRover
```
The agent checks the current project, links it to a space, and tells you when memory is ready.
Follow the complete first-run setup from Desktop installation to agent onboarding.
## Core concepts
Manage sign-in, onboarding, connected agents, teams, spaces, sharing, and sync status.
Choose where memory lives. Use private spaces, team spaces, or spaces shared with you.
Give the agent instructions for binding projects, querying memory, recording context, authenticating, and cleanup review.
Connect OpenClaw, Hermes, or VPS CLI agents such as Codex CLI, Claude Code, and OpenCode CLI.
## Choose your path
Install Desktop, sign in, connect an agent, and complete onboarding.
Install the skill on the server, use the context-engine script for OpenClaw, restart the agent, authenticate ByteRover, and then run onboarding.
Move old V3 project memory on a VPS into V4 spaces before continuing V4 work.
Learn when the agent should bind, query, record, dream, and authenticate.
# Auth
Source: https://docs.byterover.dev/v4/skill/auth
Approve ByteRover skill authentication when an agent needs account access.
Use the Auth skill when your agent says ByteRover needs authentication or cloud sync access for the current workspace.
Most users sign in through ByteRover Desktop during setup. Auth is the agent-side approval flow: the agent prints a browser URL and short code, you approve it, then the agent confirms the connection.
## Ask the agent to authenticate
Ask your agent:
```text theme={null}
Authenticate with ByteRover.
```
The agent starts the ByteRover auth flow.
Manual reference:
```bash theme={null}
node scripts/auth.mjs
```
## Open the URL
The agent will print a browser URL, a short code, and an expiry time.
Open the URL in your browser and approve the request before the code expires.
Use the URL and code printed by your own agent session. Do not copy a code from docs, screenshots, or another terminal.
## Return to the agent
After approving in the browser, return to the agent and say:
```text theme={null}
approved
```
The agent checks the auth status.
Manual reference:
```bash theme={null}
node scripts/auth.mjs status
```
## Understand the status
| Status | Meaning | What to do |
| ---------- | ----------------------------------------- | --------------------------------------------------------------- |
| `approved` | ByteRover is connected. | Continue setup or retry the original Query or Record request. |
| `pending` | The browser approval is not finished yet. | Open the URL again, approve it, then return and say `approved`. |
| `expired` | The code expired. | Start Auth again for a fresh URL and code. |
| `denied` | The browser request was rejected. | Start Auth again only if you want to connect this agent. |
## Sign out
Ask the agent:
```text theme={null}
Log out of ByteRover.
```
Manual reference:
```bash theme={null}
node scripts/logout.mjs
```
## Check sync status
If cloud sync seems stuck, ask the agent to check ByteRover sync status.
Manual reference:
```bash theme={null}
node scripts/sync.mjs status
```
If the status says `auth-expired`, run Auth again. Never paste API keys into chat to work around an auth problem.
## Next steps
Retrieve project memory now that the agent is authenticated.
Manage where memory lives and check space sync in Desktop.
# Bind
Source: https://docs.byterover.dev/v4/skill/bind
Connect a project folder to the ByteRover space your agent should use.
Use the Bind skill when a project folder should read and write memory in a specific ByteRover space.
Binding is usually handled during onboarding. Use this page when an agent reports that no space is configured, when the wrong space is selected, or when you want to make a project-to-space relationship explicit.
## Before you bind
* Install the ByteRover skill in your agent.
* Sign in to ByteRover Desktop.
* Create or select the space in ByteRover Desktop first.
* Open your agent or terminal from the project root.
The skill does not create spaces. Create the space in ByteRover Desktop, then bind the project folder to it.
## Check the current space
Ask your agent:
```text theme={null}
Check which ByteRover space this project is using.
```
The agent checks the current folder's space resolution.
Manual reference:
```bash theme={null}
node scripts/space.mjs current
```
## Bind the project to a space
Ask your agent:
```text theme={null}
Bind this project to the "" ByteRover space.
```
Replace `` with the exact space name from ByteRover Desktop.
Manual reference:
```bash theme={null}
node scripts/space.mjs bind "My Project"
```
Binding stores a local project binding so future Query and Record calls resolve to that space from the project folder.
## Verify the binding
Ask your agent:
```text theme={null}
Check ByteRover space again and confirm this project is bound correctly.
```
Manual reference:
```bash theme={null}
node scripts/space.mjs current
```
The result should point to the intended space.
## Common fixes
| Problem | What to do |
| --------------------------------- | -------------------------------------------------------------------------------- |
| Space not found | Create the space in ByteRover Desktop, then run bind again with the exact name. |
| Wrong space resolves | Run bind again from the project root with the correct space name. |
| Agent says no context tree exists | Open ByteRover Desktop and make sure the space has finished syncing, then retry. |
## Next steps
Retrieve project memory before work starts.
Save durable project knowledge after work is complete.
# Dream
Source: https://docs.byterover.dev/v4/skill/dream
Review cleanup and consolidation proposals for saved ByteRover memory.
Use the Dream skill when a space has accumulated enough memory that topics may overlap, drift, or become stale.
Dream does not edit memory. It only proposes cleanup candidates. Your agent should read the source topics, decide what is worth changing, then use the right follow-up skill command.
## When to use Dream
Use Dream after a burst of recording, before a planning round, or when query results feel noisy.
Do not run Dream on every task. The proposals are more useful when there is enough saved memory to compare.
Dream works on the space resolved from the current project folder. If the project should use a named space, bind it first with [Bind](/v4/skill/bind).
## Ask the agent to review memory
Ask your agent:
```text theme={null}
Review ByteRover memory for cleanup and consolidation opportunities.
```
The agent runs Dream from inside the project folder.
Manual reference:
```bash theme={null}
node scripts/dream.mjs --mode merge --min-score 0.3
```
## Choose a mode
Dream supports four modes.
| Mode | What it proposes |
| ------------ | -------------------------------------------------------------- |
| `merge` | Topics that cover the same ground and may be combined. |
| `link` | Topics that should reference each other but do not yet link. |
| `prune` | Topics that look stale or low-value. |
| `synthesize` | Small related topics that may read better as one larger topic. |
The default mode is `merge`.
Manual examples:
```bash theme={null}
node scripts/dream.mjs --mode link
```
```bash theme={null}
node scripts/dream.mjs --mode prune --limit 10
```
```bash theme={null}
node scripts/dream.mjs --mode synthesize
```
## Review the candidates
Dream returns JSON with candidate paths, scores, and the reason the topics were grouped.
Ask the agent to read source topics before acting:
```text theme={null}
Read the suggested Dream candidates and explain which ones are worth changing before editing memory.
```
Manual reference:
```bash theme={null}
node scripts/brv.mjs read "architecture/auth.html"
```
## Act on a proposal
Only act on candidates that still make sense after reading the source topics.
| Dream proposal | Follow-up action |
| -------------- | --------------------------------------------------------------------------------- |
| `merge` | Use `merge.mjs` to fold one topic into another and remove the loser. |
| `link` | Use [Record](/v4/skill/record) to update `related=` references. |
| `prune` | Use `prune.mjs` to remove stale topics after confirming they are safe to delete. |
| `synthesize` | Use `synthesize.mjs` to write a consolidated topic and absorb the smaller topics. |
Manual references:
```bash theme={null}
node scripts/merge.mjs auth/login.html auth/oauth.html
```
```bash theme={null}
node scripts/prune.mjs old/topic.html
```
```bash theme={null}
node scripts/synthesize.mjs auth/session-model --html '...' --absorb auth/login.html,auth/oauth.html
```
## Verify after cleanup
After acting on Dream proposals, ask the agent to query the same topic again:
```text theme={null}
Query ByteRover for the memory we just consolidated and confirm the result is clearer.
```
If the result got worse, ask the agent to explain what changed before recording more memory.
## Next steps
Approve skill authentication and check sync status.
Confirm consolidated memory reads back clearly.
# Query
Source: https://docs.byterover.dev/v4/skill/query
Retrieve relevant project memory before work starts.
Use the Query skill before non-trivial work so your agent can align with existing project decisions, patterns, and gotchas.
The normal workflow is agent-driven: ask the agent to check ByteRover, then let it use the retrieved memory while it works.
Run Query from inside the project folder. If the project should use a named space, bind it first with [Bind](/v4/skill/bind).
## Ask your agent to query
Use natural language. Include the area of the codebase or decision you are about to touch.
```text theme={null}
Before changing authentication, query ByteRover for the current desktop auth and daemon sync decisions.
```
Other examples:
```text theme={null}
Check ByteRover for testing conventions before adding these tests.
```
```text theme={null}
Query ByteRover for deployment gotchas related to the desktop app.
```
The agent should run the query from inside the project folder so ByteRover can resolve the correct space.
## Review the answer
The agent should summarize the relevant memory and show the source when ByteRover returns one.
Use the answer as project context, not as a blind command. If the recorded memory conflicts with the current task, ask the agent to explain the conflict before changing direction.
## Narrow the query
If the answer is too broad, ask a more specific follow-up:
```text theme={null}
Narrow that to auth token storage and browser approval only.
```
If the answer misses a topic you expected, mention the likely area:
```text theme={null}
Search ByteRover again, focused on the desktop daemon auth flow.
```
## Record what is missing
If nothing useful appears, continue the work. When the decision becomes clear, ask the agent to record it:
```text theme={null}
Record the auth token storage decision we just made, including why we rejected pasted tokens.
```
## Manual reference
Most users do not need to run the script directly. The connected agent runs it from the installed ByteRover skill directory.
The script shape is:
```bash theme={null}
node scripts/query.mjs "desktop auth daemon sync" --limit 5
```
The command returns JSON with:
| Field | Meaning |
| ---------------- | -------------------------------------------------------------- |
| `hits` | Ranked matching topics with path, title, score, and snippet. |
| `query` | The resolved query text. |
| `should_cite` | Whether the result set is strong enough for the agent to cite. |
| `citation_block` | A ready-to-share citation block for the matching memories. |
## Read a full topic
When a hit looks useful, read the full topic:
```bash theme={null}
node scripts/brv.mjs read "architecture/auth.html"
```
The agent should treat recorded decisions and rules as constraints unless it explains why the current task needs to diverge.
## Next steps
Save durable project knowledge after work is complete.
Review cleanup and consolidation proposals for saved memory.
# Record
Source: https://docs.byterover.dev/v4/skill/record
Save durable project knowledge after useful work is completed.
Use the Record skill after useful work so future agent sessions can inherit the decision, pattern, or gotcha instead of rediscovering it.
Recording saves knowledge into the active ByteRover space. The normal workflow is agent-driven: ask your coding agent to remember what matters, and the agent writes the structured memory through the ByteRover skill.
Run Record from inside the project folder. If the project should use a named space, bind it first with [Bind](/v4/skill/bind).
## Decide what should be remembered
Record knowledge that future sessions should reuse:
* architecture decisions and why they were made
* project conventions that are not obvious from code alone
* setup, testing, deployment, or debugging steps
* gotchas that would waste time if rediscovered later
* team preferences that should guide future work
Do not record facts that are already obvious from source code, generated files, or git history.
## Ask your agent to record it
Use natural language. Be specific about what changed and why it matters.
```text theme={null}
Record the testing strategy we just confirmed. Include when to use in-memory tests and where the fixtures live.
```
You can also ask the agent to update an existing memory:
```text theme={null}
Update ByteRover with the new authentication decision. Include the reason we switched to browser approval instead of pasted tokens.
```
The agent should choose a stable topic path, write the memory, and report where it was saved.
## Review the saved memory
Open ByteRover Desktop and review the context tree for the active space.
Check that the new memory is:
* in the correct space
* named clearly
* focused on one subject
* useful for a future session
## Query to verify
Ask the agent to retrieve the memory you just saved:
```text theme={null}
Query ByteRover for the testing strategy we recorded.
```
If the answer is too vague, ask the agent to update the record with clearer details.
## Manual reference
Most users do not need to run the script directly. The connected agent runs it from the installed ByteRover skill directory.
For a simple single-fact record, the script shape is:
```bash theme={null}
node scripts/record.mjs "testing/unit_strategy" \
--title "Unit testing strategy" \
--summary "Fast in-memory service tests for this repo" \
--keywords testing,unit,fixtures \
--body "Unit tests should run fully in memory and avoid network services unless a test is explicitly marked as integration."
```
Every command prints JSON. A successful record response includes whether the topic was created and the tree-relative path that was written.
## Structured records
For richer knowledge, the agent can pass a full `` document:
```bash theme={null}
node scripts/record.mjs "architecture/auth" --html '
Document the current authentication flow.Desktop sign-in uses browser OAuth and returns through a byterover:// deep link.This keeps credential entry in the browser and lets Desktop exchange the callback securely.Desktop sign-in returns through a byterover:// callback.'
```
Structured records rank better because ByteRover can search facts, decisions, reasons, rules, and files separately.
## Next steps
Retrieve the memory you just recorded before the next task.
Review cleanup and consolidation proposals for saved memory.