# Installation Guide

Complete setup guide for hive-mcp on Linux/macOS.

## The short way

```bash
curl -fsSL https://hive-mcp.com/install.sh | sh
```

Install with `curl -fsSL https://hive-mcp.com/install.sh | sh` then `hive setup`.
`hive setup` installs bb-mcp, publishes it at `~/.local/share/hive-mcp/bb-mcp`,
and registers `hive` with your MCP clients (Claude Code, Codex) through bb-mcp.
Already have bb-mcp checked out somewhere? Run `<that checkout>/bb-mcp setup`:
wherever bb-mcp lives becomes the reference. Verify with `bb-mcp setup --check`.

The one-liner installs the `hive` CLI and writes the setup skills into
`~/.claude/skills`. To let the assistant drive the rest, start Claude Code and
say what you want:

> help me set up the hive-mcp harness locally, I have a key

> help me set up a FOSS build of the hive-mcp harness

The skills carry the whole procedure, so the assistant drives the rest. Add
`--setup` to the one-liner to run `hive setup` unattended in the same pass, or
run the three commands yourself:

```bash
hive detect     # what is already here
hive setup      # prerequisites, bb-mcp checkout, then `bb-mcp setup --client all`
hive doctor     # every check, including `bb-mcp setup --check`
```

Every file the installer downloads is checked against a signed `SHA256SUMS`
before it is made executable. [[Verifying-The-Install]] says what that covers,
what it does not, and how to verify the script itself against a second origin
before running it.

Everything below is the same path done by hand, and the reference for when a
step fails.

## Prerequisites

Install these before proceeding:

| Requirement | Version | Installation |
|-------------|---------|--------------|
| **Claude Code CLI** | Latest | [claude.ai/download](https://claude.ai/download) |
| **Java** | 21 | `sudo apt install openjdk-21-jdk` (CI and the container image both run 21) |
| **Clojure CLI** | 1.12+ | [clojure.org/guides/install_clojure](https://clojure.org/guides/install_clojure) |
| **Docker** | 20+ | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
| **Git** | 2.0+ | `sudo apt install git` |
| **Babashka** | 1.3+ | runs bb-mcp, the MCP entry point every client launches |

Optional, each degrading to a dormant feature rather than a failed boot:

| Optional | For |
|----------|-----|
| **Emacs** 28.1+ | the Emacs vessel, the swarm vterm UI, buffer integration |
| **tmux** + Python 3 + libtmux | the headless vessel |
| **Ollama** | local embeddings, so memory search is semantic |

### Quick Install (Ubuntu/Debian)

```bash
# Java
sudo apt install openjdk-21-jdk

# Clojure CLI
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh
chmod +x linux-install.sh
sudo ./linux-install.sh

# Babashka
bash < <(curl -s https://raw.githubusercontent.com/babashka/babashka/master/install)

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group change
```

### Quick Install (macOS)

```bash
brew install openjdk@21 clojure/tools/clojure borkdude/brew/babashka
brew install --cask docker
```

## Step 1: Clone Repositories

### Option A: Automated Setup (Recommended)

```bash
curl -fsSL https://hive-mcp.com/install.sh | sh
hive setup
```

The CLI handles prerequisites, dependency download and the bb-mcp checkout: it
reuses the bb-mcp that `~/.local/share/hive-mcp/bb-mcp` already points at, or
clones it to `${BB_MCP_DIR:-$HOME/bb-mcp}`, then runs
`<bb-mcp>/bb-mcp setup --client all`. Client registration lives only in
`bb-mcp setup`; the CLI registers nothing itself. It is idempotent: a step whose
check already passes is skipped, and a failing step rolls back what it did.

With a Go toolchain you can build it instead:

```bash
go install github.com/hive-agi/hive-mcp-cli/cmd/hive@latest
hive guide --install     # the setup skills, which the one-liner writes for you
```

### Option B: Manual Setup

```bash
# Choose your installation directory
cd ~/projects  # or wherever you prefer

# Clone hive-mcp (no submodules needed!)
git clone https://github.com/hive-agi/hive-mcp.git

# Clone bb-mcp (the MCP entry point your clients launch)
git clone https://github.com/hive-agi/bb-mcp.git
```

The rest of this page assumes both clones sit in `~/projects`; adjust the paths if
you chose elsewhere.

**Note:** All dependencies are fetched automatically via git deps - no submodules required.

## Step 2: Publish bb-mcp and register with your MCP clients

```bash
~/projects/bb-mcp/bb-mcp setup --dry-run   # print the plan, write nothing
~/projects/bb-mcp/bb-mcp setup             # do it
```

`bb-mcp setup` is idempotent and reports each step:

- **anchor**: links `~/.local/share/hive-mcp/bb-mcp` to this checkout. Wherever
  bb-mcp lives becomes the reference; move it and rerun to repoint the link.
- **claude**: when the `claude` CLI is on PATH, registers the server `hive` at
  user scope, launching `~/.local/share/hive-mcp/bb-mcp/start-bb-mcp.sh`.
  `--scope project` writes `.mcp.json` in the current directory instead.
- **codex**: when `~/.codex` exists, upserts `[mcp_servers.hive]` in
  `~/.codex/config.toml`, keeping every other table and comment (backed up once
  first).

Flags: `--client claude|codex|all`, `--scope user|project`, `--port N` (only
when the backend is not on nREPL 7910), `--dry-run`, `--check`.

No shell variables are needed. `start-bb-mcp.sh` takes the project directory
from the client's working directory and the nREPL port from
`<project>/.nrepl-port`, else 7910. `BB_MCP_NREPL_PORT` overrides the port when
you run the backend elsewhere; `bb-mcp setup --port N` writes it into the client
entry for you. `OPENROUTER_API_KEY`, if you use LLM delegation, belongs in the
backend's environment, see [[Infrastructure-Setup]].

To register by hand, a client that expands environment variables takes:

```json
{
  "mcpServers": {
    "hive": {
      "command": "${HOME}/.local/share/hive-mcp/bb-mcp/start-bb-mcp.sh",
      "env": { "BB_MCP_NREPL_PORT": "7910" }
    }
  }
}
```

A client without expansion takes the expanded anchor path
(`/home/<you>/.local/share/hive-mcp/bb-mcp/start-bb-mcp.sh`), never the path of
the real checkout.

## Step 3: Download Dependencies

```bash
cd ~/projects/hive-mcp

# Download Clojure dependencies (may take 1-2 minutes first time)
clojure -P

# Verify it works
clojure -M:dev -e "(println :ok)"
# Should print: :ok
```

## Step 4: Configure Emacs

See [[Emacs-Configuration]] for detailed setup.

**Quick start for Doom Emacs:**

Add to `~/.doom.d/packages.el`:
```elisp
(package! claude-code-ide
  :recipe (:host github :repo "BuddhiLW/claude-code-ide.el"))
;; NOTE: Fork required for hive-mcp swarm integration.
;; Adds --system-prompt file support for preset injection.
(package! web-server)
```

> **Why a fork?** The swarm needs to inject custom system prompts when spawning lings.
> The fork adds a `system-prompt-file` parameter to `claude-code-ide--build-claude-command`
> that allows passing preset content via `--system-prompt $(cat file)`.
> See [fork](https://github.com/BuddhiLW/claude-code-ide.el) vs [upstream](https://github.com/manzaltu/claude-code-ide.el).

Then run:
```bash
doom sync
```

## Step 5: Start Infrastructure

See [[Infrastructure-Setup]] for details. Quick version:

```bash
cd ~/projects/hive-mcp

# Start Chroma (vector database) and observability stack
docker compose up -d chroma

# Install Ollama and pull embedding model
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text:latest

# Verify
curl http://localhost:8000/api/v1/heartbeat
ollama list | grep nomic
```

## Step 6: Start Emacs Daemon

```bash
# Start Emacs in daemon mode
emacs --daemon

# Verify it's running
emacsclient -e '(emacs-version)'
# Should print your Emacs version
```

## Step 7: Start the backend and verify the registration

```bash
# Backend: the hive-mcp JVM on nREPL 7910 (services, starter pack, host)
cd ~/projects/hive-mcp && bin/hive-mcp-foss

# Client side, registered in Step 2 (or by `hive setup`)
bb-mcp setup --check     # anchor, client entries, babashka, nREPL reachability
claude mcp list          # should show: hive, launched from the anchor
```

`--check` exits non-zero when a check fails. An nREPL that does not answer is
only a warning; it means the backend is not up yet.

## Step 8: Verify Installation

```bash
# Start Claude Code
claude

# Test the connection
> Check if Emacs is available using emacs_status
```

Expected response:
```clojure
{:emacs-available true
 :server-running true
 :emacs-pid 12345
 :server-socket "/run/user/1000/emacs/server"}
```

## Next Steps

- [[Infrastructure-Setup]] - Configure Docker services, Ollama, OpenRouter
- [[Emacs-Configuration]] - Detailed Emacs module configuration
- [[Troubleshooting]] - Common issues and solutions

## Uninstallation

```bash
# Remove MCP registration
claude mcp remove hive --scope user
rm ~/.local/share/hive-mcp/bb-mcp     # the anchor symlink

# Stop Docker services
cd ~/projects/hive-mcp
docker compose down -v

# Remove repositories (optional)
rm -rf ~/projects/hive-mcp ~/projects/bb-mcp
```