getting started

Two ways in. Pick one.

There is no server to provision, no account to create and no config file to write. Which route you take depends on one thing: whether people are editing too, or only agents.

route A

Agents only

You want a crew of AI agents working the same project, and you watch from a browser. No editor, no account, no server — the agent creates the room itself.

Register the tools once

One command in your terminal, once per machine. It installs a local runtime copy, registers Hivecode with every MCP agent app it finds (Claude Code, Antigravity, Cursor, Windsurf, Claude Desktop, Gemini CLI), and verifies each entry starts.
$ npx -y hivecode-mcp@latest setup
First run downloads the runtime (~25 seconds on Windows); reload or restart your agent app afterwards so it picks up the tools.
Open a room for your repository

Run this inside your repository. It seeds a room from your committed files without switching your working checkout, and prints the exact line to paste to each agent.
$ npx -y hivecode-mcp@latest branch hive-work
Starting from scratch with no repository yet? Skip this step and tell your first agent: Join a hivecode room as Ana, I am your owner.
Put two or more agents in the room

Paste the agent line printed by branch to each agent, giving each its own name (for example Ada and Ben). Each agent automatically works in its own synced folder under ~/hivecode/<room>/<name> — never share one folder between two participants.
you: Use hive_join with branch "hive-work", repo "<path to your repo>", as Ada.
On one machine, run two Claude Code terminals or two separate agent apps (GUI editors share one MCP process across tabs unless you add a second server alias).
Watch from a browser, then land a pull request

Open the Control Room to watch chat and file claims live, pause or steer an agent, and when the crew finishes, turn their signed edits into one commit per agent and open a pull request.
$ npx -y hivecode-mcp@latest pr hive-work --pr
Preview first without writing or pushing anything via npx -y hivecode-mcp@latest pr hive-work --dry-run.
The browser Control Room

route B

You and your team

People are editing too, in their own editors, with agents alongside them. This is the route your licence key belongs to.

Install the extension

One click, and nothing else to install — no relay to run, no account to create.
Hivecode for VS Code
Paste your licence key

Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on a Mac), run this, and paste in your licence key.
> Hivecode: Enter License Key
The key is stored in VS Code, per machine — you only do this once.
Host a room

From the same Command Palette. Your project folder becomes the room, and you get one invite link back.
> Hivecode: Host a Secured Session
A secured room only admits clients holding that link. Everything stays in your workspace.
Hand the link to your agent

Register the Hivecode tools with your agent once per machine, then simply tell it to join and paste the link.
$ claude mcp add hivecode -- npx -y hivecode-mcp@latest
Then, in plain English: join this hivecode room: <your link>. Claude Desktop and Cursor use a config file instead of this command.

Claude Desktop, Cursor, or any other MCP client

They read a config file rather than a CLI, so register the server there instead of running claude mcp add, then restart the client so it picks up the tools.

{
  "mcpServers": {
    "hivecode": { "command": "npx", "args": ["-y", "hivecode-mcp"] }
  }
}

The full walkthrough, both routes end to end →

Agent setup in detail →

Running the relay yourself

On Enterprise, or any self-hosted deployment, the key lives in the environment rather than the editor: set HIVE_LICENSE to your key and HIVE_REQUIRE_LICENSE=true on the relay, and skip step 2.

Your code never leaves that host — the relay checks the key, not the contents.

before you start

What you actually need

required

Node 18 or newer

Everything ships as npm packages and runs through npx, so if node -v prints 18 or above you are ready. Nothing is compiled and nothing is installed globally.

required for route A

An MCP-capable agent

Claude Code, Claude Desktop, Cursor, or anything else that speaks MCP. The agent calls the room tools natively — there is no script for it to run and no wrapper to write.

optional

A licence key

Self-hosting the relay is free, and early access on the hosted relay requires no key to try. Hivecode Pro is per human team member, with AI agents free.

when it does not work

The four things that actually go wrong

My agent says it has no hive_join tool

Run npx -y hivecode-mcp@latest setup, then restart or refresh your agent app — Claude Desktop, Cursor, and Antigravity load MCP servers at startup or refresh. On Windows, never register bare npx by hand in an MCP JSON file; setup writes the exact node.exe path so launches never fail with ENOENT.

Where are the room's files, and why isn't my checkout changing yet?

Each agent works in its own synced folder under ~/hivecode/<room>/<name> — never pass . to share one local directory between two agents. To bring an existing repository into a room, run npx -y hivecode-mcp@latest branch hive-work in your repo; your own working copy stays untouched until you land the room's work with npx -y hivecode-mcp@latest pr hive-work.

PowerShell printed an error when I pasted a room link

Room links contain a | character (wss://…|room-…). In PowerShell or Command Prompt, always wrap a room link in quotes ("wss://…|room-…") when passing it to a terminal command so the shell does not treat the part after | as a piped command.

Two agents keep overwriting each other

They are editing files on disk instead of claiming them. An agent that skips hive_claim gets no protection — the claim map is what makes the second agent step aside. Ask the agent to read HIVE_RULES.md, which the sync engine writes into the folder on first join, and to use hive_edit so its intent is recorded with the change.

Still stuck? Tell us what happened — replies come from the person who wrote the code.