# Installation Guide

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

## Prerequisites

Install these before proceeding:

| Requirement | Version | Installation |
|-------------|---------|--------------|
| **Emacs** | 28.1+ | [gnu.org/software/emacs](https://www.gnu.org/software/emacs/) |
| **Claude Code CLI** | Latest | [claude.ai/download](https://claude.ai/download) |
| **Java** | 17+ | `sudo apt install openjdk-17-jdk` |
| **Clojure CLI** | 1.11+ | [clojure.org/guides/install_clojure](https://clojure.org/guides/install_clojure) |
| **Babashka** | 1.3+ | [babashka.org](https://babashka.org) |
| **Docker** | 20+ | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
| **Git** | 2.0+ | `sudo apt install git` |

### Quick Install (Ubuntu/Debian)

```bash
# Java
sudo apt install openjdk-17-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@17 clojure/tools/clojure borkdude/brew/babashka
brew install --cask docker
```

## Step 1: Clone Repositories

### Option A: Automated Setup (Recommended)

If you have Go installed:

```bash
go install github.com/hive-agi/hive-mcp-cli/cmd/hive@latest
hive setup
```

The CLI handles cloning, dependency download, and MCP registration automatically.

### 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 (lightweight MCP proxy)
git clone https://github.com/hive-agi/bb-mcp.git
```

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

## Step 2: Set Environment Variables

Add these to your shell config (`~/.bashrc` or `~/.zshrc`):

```bash
# Required: Paths to repositories (adjust to your clone locations)
export HIVE_MCP_DIR="$HOME/projects/hive-mcp"
export BB_MCP_DIR="$HOME/projects/bb-mcp"

# Optional: OpenRouter API key for LLM delegation
export OPENROUTER_API_KEY="sk-or-v1-..."

# Optional: Custom ports (defaults shown)
export BB_MCP_NREPL_PORT=7910
```

Reload your shell:
```bash
source ~/.bashrc  # or ~/.zshrc
```

**Important:** All commands in this wiki use `$HIVE_MCP_DIR` and `$BB_MCP_DIR`. Set these before proceeding.

## Step 3: Download Dependencies

```bash
cd $HIVE_MCP_DIR

# 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 $HIVE_MCP_DIR

# 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: Register with Claude Code

```bash
# Register hive-mcp as "emacs" MCP server
claude mcp add emacs --scope user -- \
  $HIVE_MCP_DIR/start-bb-mcp.sh

# Verify registration
claude mcp list
# Should show: emacs (172 tools)
```

## 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 emacs --scope user

# Stop Docker services
cd $HIVE_MCP_DIR
docker compose down -v

# Remove repositories (optional)
rm -rf $HIVE_MCP_DIR $BB_MCP_DIR
```