# Emacs Configuration

This guide covers Emacs integration for hive-mcp. Whether you use vanilla Emacs or Doom Emacs, follow the relevant sections to configure your environment reliably.

**OPS PRINCIPLES:**
- Configs should be **idempotent** (safe to re-evaluate)
- Each variable is explained with its **purpose** and **failure modes**
- Verification steps prevent "works on my machine" issues
- Load order matters - we explain **why**

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Vanilla Emacs Minimal Setup](#vanilla-emacs-minimal-setup)
3. [Doom Emacs Full Configuration](#doom-emacs-full-configuration)
4. [Key Variables Reference](#key-variables-reference)
5. [Addon Loading Order](#addon-loading-order)
6. [WebSocket Channel Setup](#websocket-channel-setup)
7. [Verification Steps](#verification-steps)
8. [Common Mistakes and Fixes](#common-mistakes-and-fixes)

---

## Prerequisites

### Required Before This Guide

| Requirement | Verification | Guide |
|-------------|--------------|-------|
| Emacs 28.1+ | `M-x emacs-version` | - |
| Emacs daemon running | `emacsclient -e '(emacs-version)'` | Below |
| hive-mcp cloned | `ls /path/to/hive-mcp/elisp/hive-mcp.el` | [[Installation]] |
| websocket.el installed | `M-x describe-package RET websocket` | Below |
| transient.el (0.4.0+) | Usually bundled with Emacs 28+ | - |

### Optional Infrastructure (For Semantic Search)

The following are **optional** - hive-mcp works without them using keyword-based memory search:

| Component | Needed For | Setup Guide |
|-----------|------------|-------------|
| Docker + Chroma | Semantic memory search | [[Infrastructure-Setup#2-chroma-vector-database]] |
| Ollama + nomic-embed-text | Local embeddings | [[Infrastructure-Setup#3-ollama-local-embeddings]] |
| OpenRouter API key | Agent delegation to cloud LLMs | [[Infrastructure-Setup#4-openrouter-cloud-llm-api]] |

**Recommended order:**
1. Complete this Emacs Configuration guide first (basic functionality works)
2. Then follow [[Infrastructure-Setup]] for semantic search
3. Revisit this guide's [Chroma Variables](#chroma-variables-hive-mcp-chromael) section after infrastructure is running

### Start Emacs Daemon (Required for emacsclient)

```bash
# Add to ~/.bashrc or run manually
emacs --daemon

# Verify
emacsclient -e '(+ 1 1)'
# Should return: 2
```

---

## Vanilla Emacs Minimal Setup

This is the minimal config to get hive-mcp working. Add to `~/.emacs.d/init.el`:

```elisp
;;; hive-mcp minimal configuration

;; 1. Add hive-mcp to load-path (REQUIRED)
;; The order matters: elisp/ BEFORE elisp/addons/
(add-to-list 'load-path "/path/to/hive-mcp/elisp")
(add-to-list 'load-path "/path/to/hive-mcp/elisp/addons")

;; 2. Install required packages (if not present)
(unless (package-installed-p 'websocket)
  (package-refresh-contents)
  (package-install 'websocket))

;; 3. Load core module (REQUIRED)
(require 'hive-mcp)

;; 4. Enable the global minor mode (REQUIRED)
(hive-mcp-mode 1)

;; 5. Start Emacs server for emacsclient (REQUIRED)
;; Idempotent: safe to call multiple times
(unless (server-running-p)
  (server-start))
```

### Minimal with Commonly Used Addons

```elisp
;;; hive-mcp with common addons

(add-to-list 'load-path "/path/to/hive-mcp/elisp")
(add-to-list 'load-path "/path/to/hive-mcp/elisp/addons")

;; Pre-configure before loading (avoids startup warnings)
(setq hive-mcp-channel-auto-connect nil)  ; Disable old Unix socket
(setq hive-mcp-channel-ws-auto-connect t) ; Enable WebSocket

(require 'hive-mcp)
(hive-mcp-mode 1)

;; Load addons with graceful failure (nil = don't error if missing)
(require 'hive-mcp-magit nil t)      ; Git integration
(require 'hive-mcp-projectile nil t) ; Project navigation

;; WebSocket channel for real-time events (RECOMMENDED)
(require 'hive-mcp-channel-ws nil t)

;; Start server
(unless (server-running-p)
  (server-start))
```

---

## Doom Emacs Full Configuration

Doom Emacs requires configuration in multiple files. Follow this order.

### Step 1: packages.el

Add to `~/.doom.d/packages.el`:

```elisp
;; Required for WebSocket communication
(package! websocket)

;; Required: claude-code-ide for swarm terminal integration
;; NOTE: Using fork with system-prompt-file support for preset injection
(package! claude-code-ide
  :recipe (:host github :repo "BuddhiLW/claude-code-ide.el"))

;; Required by claude-code-ide
(package! web-server)
```

> **Why the fork?** The swarm needs to inject custom system prompts (presets) when spawning lings.
> The fork adds a `system-prompt-file` parameter to `claude-code-ide--build-claude-command`
> that passes preset content via `--system-prompt $(cat file)`. Without this, lings spawn
> without their coordinator/worker presets.
>
> See [fork](https://github.com/BuddhiLW/claude-code-ide.el) vs [upstream](https://github.com/manzaltu/claude-code-ide.el).

**WHY:** Doom uses straight.el for package management. These declarations ensure packages are available before config.el runs.

### Step 2: config.el

Add to `~/.doom.d/config.el`:

```elisp
;;; hive-mcp full configuration for Doom Emacs

;; Load websocket before channel modules need it
(use-package! websocket)
(use-package! web-server)

;;;; ============================================================
;;;; SECTION 1: PATHS AND ROOT DIRECTORY
;;;; ============================================================

;; Define the hive-mcp installation path
;; Option A: Using environment variable
(defvar hive-mcp-root (expand-file-name "gitthings/hive-mcp" (getenv "DOTFILES"))
  "Root directory of hive-mcp installation.")

;; Option B: Absolute path (uncomment and adjust)
;; (defvar hive-mcp-root "/home/youruser/hive-mcp")

;; Add to load-path: ORDER MATTERS - core before addons
(add-to-list 'load-path (concat hive-mcp-root "/elisp"))
(add-to-list 'load-path (concat hive-mcp-root "/elisp/addons"))

;;;; ============================================================
;;;; SECTION 2: PRE-CONFIGURATION (BEFORE LOADING MODULES)
;;;; ============================================================
;; Set these BEFORE require statements to avoid initialization issues

;; --- CIDER/nREPL Configuration ---
;; Don't start separate nREPL - MCP server embeds one
(setq hive-mcp-cider-auto-start-nrepl nil)
;; Connect to MCP server's embedded nREPL
(setq hive-mcp-cider-auto-connect t)
;; Must match deps.edn :nrepl alias port
(setq hive-mcp-cider-nrepl-port 7910)
;; Project directory for CIDER
(setq hive-mcp-cider-project-dir hive-mcp-root)

;; --- Addon Loading Configuration ---
;; List addons to load immediately (not waiting for trigger packages)
(setq hive-mcp-addon-always-load '(cider org-kanban swarm projectile magit chroma docs))

;; --- Channel Configuration ---
;; IMPORTANT: Disable old Unix socket channel (superseded by WebSocket)
(setq hive-mcp-channel-auto-connect nil)

;; --- Kanban Configuration ---
(setq hive-mcp-kanban-org-file (concat hive-mcp-root "/kanban.org"))
;; Generate UUID with: M-x org-id-uuid
(setq hive-mcp-kanban-default-project "YOUR-PROJECT-UUID-HERE")

;; --- Chroma Vector DB Configuration ---
(setq hive-mcp-chroma-auto-start t)        ; Auto-start Docker container
(setq hive-mcp-chroma-host "localhost")
(setq hive-mcp-chroma-port 8000)
(setq hive-mcp-chroma-embedding-provider 'ollama)
(setq hive-mcp-chroma-ollama-model "nomic-embed-text")

;; --- Swarm Orchestration Configuration ---
(setq hive-mcp-swarm-presets-dir (concat hive-mcp-root "/presets"))
(setq hive-mcp-swarm-terminal 'claude-code-ide)  ; Options: claude-code-ide, vterm, eat
(setq hive-mcp-swarm-max-slaves 30)              ; Max concurrent lings
(setq hive-mcp-swarm-max-depth 3)                ; Recursion limit
(setq hive-mcp-swarm-prompt-mode 'human)         ; Human-in-the-loop for permissions

;; --- Claude Code IDE Configuration (if using swarm) ---
(setq claude-code-ide-enable-mcp-server t)
(setq claude-code-ide-mcp-allowed-tools nil)  ; nil = all tools allowed

;;;; ============================================================
;;;; SECTION 3: CORE MODULE LOADING
;;;; ============================================================

;; Load core hive-mcp (loads most submodules automatically)
(require 'hive-mcp)
(hive-mcp-mode 1)

;; Load transient menus (optional but recommended)
(require 'hive-mcp-transient)

;;;; ============================================================
;;;; SECTION 4: ADDON LOADING
;;;; ============================================================
;; Addons extend functionality. Load order matters for dependencies.

;; Addon system (auto-loads addons when trigger packages load)
(require 'hive-mcp-addons)

;; CIDER integration (Clojure REPL)
(require 'hive-mcp-cider nil t)

;; Org-kanban requires evil-define-key - defer until evil loads
(after! evil
  (require 'hive-mcp-org-kanban nil t))

;; Swarm orchestration (multi-agent)
(require 'hive-mcp-swarm nil t)
(setq hive-mcp-swarm-prompt-mode 'human)  ; Reinforce after load

;; Project and Git integration
(require 'hive-mcp-projectile nil t)
(require 'hive-mcp-magit nil t)

;; Vector database for semantic search
(require 'hive-mcp-chroma nil t)

;; Documentation generation
(require 'hive-mcp-docs nil t)

;;;; ============================================================
;;;; SECTION 5: WEBSOCKET CHANNEL SETUP
;;;; ============================================================
;; WebSocket enables push-based real-time events from the Clojure server

(require 'hive-mcp-channel-ws nil t)

;; Configure WebSocket connection
(setq hive-mcp-channel-ws-url "ws://localhost:9999")  ; Must match Clojure server
(setq hive-mcp-channel-ws-auto-connect t)
(setq hive-mcp-channel-ws-startup-delay 5.0)  ; Wait for MCP server to start
(setq hive-mcp-channel-ws-keepalive-interval 25.0)  ; Prevent connection drops

;; Register handlers for hivemind push events
(with-eval-after-load 'hive-mcp-channel-ws
  ;; Progress updates from agents
  (hive-mcp-channel-ws-on "hivemind-progress"
    (lambda (msg)
      (message "[Hivemind] %s: %s"
               (cdr (assoc 'agent-id msg))
               (cdr (assoc 'message (cdr (assoc 'data msg)))))))

  ;; Task completion notifications
  (hive-mcp-channel-ws-on "hivemind-completed"
    (lambda (msg)
      (message "[Hivemind] %s completed: %s"
               (cdr (assoc 'agent-id msg))
               (cdr (assoc 'message (cdr (assoc 'data msg)))))))

  ;; Error notifications (critical)
  (hive-mcp-channel-ws-on "hivemind-error"
    (lambda (msg)
      (display-warning 'hive-mcp
        (format "Agent %s error: %s"
                (cdr (assoc 'agent-id msg))
                (cdr (assoc 'message (cdr (assoc 'data msg)))))
        :error))))

;; Enable auto-loading for feature-triggered addons
(hive-mcp-addons-auto-load)

;;;; ============================================================
;;;; SECTION 6: KEYBINDINGS
;;;; ============================================================

(map! :leader
      (:prefix-map ("b" . "buddhi")
       (:prefix ("m" . "mcp")
        :desc "MCP menu" "m" #'hive-mcp-transient-main
        :desc "CIDER menu" "c" #'hive-mcp-cider-transient
        :desc "Kanban menu" "k" #'hive-mcp-kanban-transient
        :desc "Swarm menu" "s" #'hive-mcp-swarm-transient
        :desc "Projectile menu" "p" #'hive-mcp-projectile-transient
        :desc "Magit/Git menu" "g" #'hive-mcp-magit-transient
        :desc "Chroma/Vector menu" "v" #'hive-mcp-chroma-transient
        :desc "Docs menu" "d" #'hive-mcp-docs-transient)))
```

### Step 3: Sync Doom

After editing both files:

```bash
doom sync

# If you see errors, try:
doom sync -u  # Also update packages
```

---

## Key Variables Reference

### Core Variables (hive-mcp.el)

| Variable | Default | Purpose | Failure Mode |
|----------|---------|---------|--------------|
| `hive-mcp-auto-initialize` | `t` | Init memory/workflows when mode enables | Set to nil delays init until manual call |
| `hive-mcp-load-builtin-workflows` | `t` | Load wrap/catchup workflows | Set to nil breaks `/wrap` and `/catchup` |
| `hive-mcp-auto-enable` | `nil` | Auto-enable mode at startup | Rarely needed; mode enables via require |
| `hive-mcp-setup-addons` | `t` | Enable addon loading system | Set to nil requires manual addon loading |

### Channel Variables (hive-mcp-channel.el - Legacy)

| Variable | Default | Purpose | When to Change |
|----------|---------|---------|----------------|
| `hive-mcp-channel-auto-connect` | `t` | Connect Unix socket at startup | **Set to nil** - WebSocket supersedes this |
| `hive-mcp-channel-type` | `'unix` | Transport type (unix/tcp) | Only if using legacy channel |
| `hive-mcp-channel-port` | `9998` | TCP port for bencode channel | Must match server if using TCP |

### WebSocket Variables (hive-mcp-channel-ws.el - Recommended)

| Variable | Default | Purpose | When to Change |
|----------|---------|---------|----------------|
| `hive-mcp-channel-ws-url` | `"ws://localhost:9999"` | WebSocket server URL | If server runs on different port/host |
| `hive-mcp-channel-ws-auto-connect` | `t` | Auto-connect at startup | Set to nil for manual connection control |
| `hive-mcp-channel-ws-startup-delay` | `3.0` | Seconds to wait before connecting | Increase if MCP server starts slowly |
| `hive-mcp-channel-ws-reconnect-interval` | `5.0` | Base retry interval (seconds) | Lower for faster reconnects |
| `hive-mcp-channel-ws-max-reconnects` | `10` | Max retry attempts before degraded mode | Set to 0 for unlimited retries |
| `hive-mcp-channel-ws-keepalive-interval` | `25.0` | Ping interval to prevent drops | 0 disables; increase if seeing disconnects |

### CIDER Variables (hive-mcp-cider.el)

| Variable | Default | Purpose | When to Change |
|----------|---------|---------|----------------|
| `hive-mcp-cider-auto-start-nrepl` | `nil` | Start separate nREPL server | **Keep nil** - MCP server embeds nREPL |
| `hive-mcp-cider-auto-connect` | `t` | Connect CIDER to nREPL | Set nil if manually managing CIDER |
| `hive-mcp-cider-nrepl-port` | `7910` | Port for nREPL connection | Must match MCP server's nREPL port |
| `hive-mcp-cider-project-dir` | `nil` | Project root for CIDER | Set to hive-mcp-root for proper ns lookup |
| `hive-mcp-cider-connect-max-retries` | `30` | Max connection attempts | Increase if nREPL starts slowly |

### Swarm Variables (hive-mcp-swarm.el)

| Variable | Default | Purpose | When to Change |
|----------|---------|---------|----------------|
| `hive-mcp-swarm-terminal` | `'claude-code-ide` | Terminal backend | `vterm` for fallback, `eat` experimental |
| `hive-mcp-swarm-presets-dir` | `(hive-mcp)/presets` | Built-in preset directory | Usually don't change |
| `hive-mcp-swarm-custom-presets-dirs` | `nil` | Additional preset directories | Add project-specific preset folders |
| `hive-mcp-swarm-prompt-mode` | `'auto` | Permission handling | `'human` for manual approval, `'bypass` for CLI flag |
| `hive-mcp-swarm-max-slaves` | `30` | Maximum concurrent agents | Lower on resource-constrained systems |
| `hive-mcp-swarm-max-depth` | `3` | Ling recursion limit | Prevents runaway spawning |

### Chroma Variables (hive-mcp-chroma.el)

> **Note:** These variables are only relevant if you've completed [[Infrastructure-Setup#2-chroma-vector-database]]. Without Chroma, memory works using keyword/tag search instead of semantic search.

| Variable | Default | Purpose | When to Change |
|----------|---------|---------|----------------|
| `hive-mcp-chroma-auto-start` | `nil` | Auto-start Docker container | Set to `t` if you want automatic startup |
| `hive-mcp-chroma-host` | `"localhost"` | Chroma server host | If running on remote host |
| `hive-mcp-chroma-port` | `8000` | Chroma HTTP port | Must match docker-compose.yml |
| `hive-mcp-chroma-embedding-provider` | `'ollama` | Embedding source | Options: `ollama`, `openai`, `local` |
| `hive-mcp-chroma-ollama-model` | `"nomic-embed-text"` | Ollama embedding model | Must be pulled: `ollama pull nomic-embed-text` |

---

## Addon Loading Order

**WHY ORDER MATTERS:**

Addons have dependencies. Loading in wrong order causes:
- Symbol void errors (function not defined)
- Missing features (hooks not registered)
- Silent failures (addon loads but does nothing)

### Correct Load Order

```
1. hive-mcp.el (CORE)
   └── Requires: hive-mcp-memory, hive-mcp-context, hive-mcp-api,
                 hive-mcp-addons, hive-mcp-channel, hive-mcp-hivemind

2. hive-mcp-transient (OPTIONAL)
   └── Requires: transient.el (bundled with Emacs 28+)

3. hive-mcp-cider (ADDON)
   └── Requires: hive-mcp-api (from core)
   └── Soft-requires: cider (graceful if missing)

4. hive-mcp-swarm (ADDON)
   └── Requires: hive-mcp-graceful
   └── Requires: swarm submodules (events, prompts, presets, terminal)
   └── Soft-requires: vterm OR eat OR claude-code-ide

5. hive-mcp-org-kanban (ADDON)
   └── Requires: evil (in Doom) for keybindings
   └── WHY after!: evil-define-key must exist first

6. hive-mcp-channel-ws (CHANNEL)
   └── Requires: websocket.el
   └── WHY last: Handlers depend on other modules being loaded
```

### The Addon System

hive-mcp uses two addon loading mechanisms:

**1. Always-load addons** (immediate):
```elisp
(setq hive-mcp-addon-always-load '(cider swarm magit))
;; These load during hive-mcp-initialize
```

**2. Auto-load addons** (deferred):
```elisp
;; Defined in hive-mcp-addon-auto-load-list:
;; '((cider . cider)        ; Load hive-mcp-cider when cider loads
;;   (swarm . vterm)        ; Load hive-mcp-swarm when vterm loads
;;   (org-kanban . org))    ; etc.
```

**Why both mechanisms?**
- Always-load: For addons you always want, regardless of packages
- Auto-load: For addons that only make sense with their base package

---

## WebSocket Channel Setup

The WebSocket channel provides **real-time push events** from the Clojure MCP server to Emacs. This is critical for:
- Hivemind agent status updates
- Task completion notifications
- Human-in-the-loop decisions (ask/respond)

### Architecture

```
MCP Server (Clojure)              Emacs
    │                               │
    │ Aleph WebSocket :9999         │
    │◄──────────────────────────────┤ websocket.el connects
    │                               │
    │ JSON: {type: "hivemind-..."}  │
    ├──────────────────────────────►│ hive-mcp-channel-ws receives
    │                               │
    │                               │ Dispatches to handlers
    │                               ▼
    │                         (hive-mcp-channel-ws-on ...)
```

### Connection Lifecycle

1. **Startup**: After `hive-mcp-channel-ws-startup-delay` seconds, attempts connection
2. **On failure**: Retries with exponential backoff (base: `reconnect-interval`)
3. **After max retries**: Enters "graceful degradation" mode (queues messages)
4. **Manual recovery**: `M-x hive-mcp-channel-ws-connect`

### Registering Event Handlers

```elisp
;; Handler receives parsed JSON as alist
(hive-mcp-channel-ws-on "event-type"
  (lambda (msg)
    ;; msg is: ((type . "event-type") (agent-id . "...") (data . ...))
    (let ((agent (cdr (assoc 'agent-id msg)))
          (data (cdr (assoc 'data msg))))
      ;; Process event
      )))

;; Remove handler
(hive-mcp-channel-ws-off "event-type")
```

### Available Event Types

| Event | When Emitted | Data Fields |
|-------|--------------|-------------|
| `hivemind-started` | Agent begins task | agent-id, task |
| `hivemind-progress` | Agent reports progress | agent-id, message, data |
| `hivemind-completed` | Agent finishes task | agent-id, result |
| `hivemind-error` | Agent encounters error | agent-id, error |
| `hivemind-blocked` | Agent needs input | agent-id, reason |
| `hivemind-ask` | Agent requests decision | ask-id, agent-id, question, options |

---

## Verification Steps

After configuration, verify each component works:

### 1. Core Module

```
M-x hive-mcp-mode          ; Should show " MCP" in mode line
M-x hive-mcp-show-context  ; Should show buffer/project info
```

### 2. Memory System

```
M-x eval-expression RET
(hive-mcp-api-memory-add "note" "Test note" '("test"))
; Should return success message

M-x eval-expression RET
(hive-mcp-api-memory-query "note")
; Should show your test note
```

### 3. WebSocket Channel

```
M-x hive-mcp-channel-ws-status
; Should show "Connected" if MCP server is running
; Or "Disconnected" with reconnect info

M-x hive-mcp-channel-ws-connect  ; Manual connect attempt
```

### 4. Hivemind UI

```
M-x hive-mcp-hivemind-status  ; Shows agents and pending asks
M-x hive-mcp-hivemind-show-log  ; Shows event log
```

### 5. Addons

```
M-x hive-mcp-addon-info  ; Lists available/loaded addons

; For specific addons:
M-x hive-mcp-swarm-status  ; Swarm agent status
M-x cider-connected-p  ; CIDER connection (if using)
```

### 6. Full Integration Test

```bash
# Start Claude Code CLI
claude

# In Claude, test Emacs connection:
> Check Emacs status using emacs_status
# Expected: {:emacs-available true, :server-running true, ...}

> Get current context using mcp_get_context
# Expected: Buffer, project, git info
```

---

## Common Mistakes and Fixes

### Mistake 1: Wrong load-path order

**Symptom:** `Cannot open load file: hive-mcp-swarm-events`

**Cause:** Addons directory not in load-path, or added after require

**Fix:**
```elisp
;; CORRECT: Add paths BEFORE require
(add-to-list 'load-path "/path/to/hive-mcp/elisp")
(add-to-list 'load-path "/path/to/hive-mcp/elisp/addons")
(require 'hive-mcp)  ; Now it can find submodules

;; WRONG: Require before paths
(require 'hive-mcp)  ; Fails - can't find it
(add-to-list 'load-path ...)
```

### Mistake 2: Both channels enabled

**Symptom:** Duplicate events, connection errors

**Cause:** Both Unix socket and WebSocket channels trying to connect

**Fix:**
```elisp
;; Disable legacy channel
(setq hive-mcp-channel-auto-connect nil)
;; Enable WebSocket (recommended)
(setq hive-mcp-channel-ws-auto-connect t)
```

### Mistake 3: CIDER auto-start conflicts

**Symptom:** Two nREPL servers, port conflicts

**Cause:** Both CIDER and MCP server trying to start nREPL

**Fix:**
```elisp
;; Don't start separate nREPL - MCP server embeds one
(setq hive-mcp-cider-auto-start-nrepl nil)
;; Connect to MCP's nREPL instead
(setq hive-mcp-cider-auto-connect t)
(setq hive-mcp-cider-nrepl-port 7910)
```

### Mistake 4: Missing websocket.el

**Symptom:** `Cannot open load file: websocket`

**Cause:** websocket package not installed

**Fix (vanilla Emacs):**
```elisp
(package-install 'websocket)
```

**Fix (Doom):**
```elisp
;; In packages.el:
(package! websocket)

;; Then run:
;; doom sync
```

### Mistake 5: org-kanban before evil

**Symptom:** `Symbol's function definition is void: evil-define-key`

**Cause:** Doom loads org-kanban before evil mode

**Fix:**
```elisp
;; CORRECT: Defer loading
(after! evil
  (require 'hive-mcp-org-kanban nil t))

;; WRONG: Load immediately
(require 'hive-mcp-org-kanban)  ; Fails in Doom
```

### Mistake 6: Emacs server not running

**Symptom:** `emacsclient: can't find socket`

**Cause:** Emacs daemon not started, or server-start not called

**Fix:**
```bash
# Start daemon
emacs --daemon

# Or in config (idempotent):
(unless (server-running-p)
  (server-start))
```

### Mistake 7: WebSocket connects before server

**Symptom:** Rapid reconnect attempts at startup

**Cause:** Emacs connects before MCP server is ready

**Fix:**
```elisp
;; Increase startup delay
(setq hive-mcp-channel-ws-startup-delay 5.0)  ; or 10.0 for slow systems
```

---

## Quick Reference

### Essential Variables (Copy-Paste Ready)

```elisp
;; Minimal safe configuration
(setq hive-mcp-channel-auto-connect nil)        ; Disable legacy
(setq hive-mcp-channel-ws-auto-connect t)       ; Enable WebSocket
(setq hive-mcp-channel-ws-url "ws://localhost:9999")
(setq hive-mcp-channel-ws-startup-delay 5.0)
(setq hive-mcp-cider-auto-start-nrepl nil)      ; Use MCP's nREPL
(setq hive-mcp-cider-nrepl-port 7910)
```

### Verification Commands

| Command | Purpose |
|---------|---------|
| `M-x hive-mcp-mode` | Enable/disable mode |
| `M-x hive-mcp-channel-ws-status` | Check WebSocket connection |
| `M-x hive-mcp-channel-ws-connect` | Manual reconnect |
| `M-x hive-mcp-addon-info` | List addon status |
| `M-x hive-mcp-hivemind-status` | View agents |
| `M-x hive-mcp-show-context` | Debug context gathering |

### Startup Order Checklist

1. [ ] Emacs daemon running (`emacs --daemon`)
2. [ ] hive-mcp load-paths added
3. [ ] Pre-configuration variables set
4. [ ] `(require 'hive-mcp)` executed
5. [ ] `(hive-mcp-mode 1)` enabled
6. [ ] Addons loaded (after core)
7. [ ] WebSocket channel configured (after addons)
8. [ ] MCP server started (`./start-bb-mcp.sh` or `./start-mcp.sh`)
9. [ ] `M-x hive-mcp-channel-ws-connect` successful

---

## Still Having Issues?

If you encounter errors not covered in Common Mistakes above, see [[Troubleshooting]] for:
- Full symptom-based error lookup
- Diagnostic commands
- Server log analysis
- Getting help

---

## Related Pages

| Page | Description |
|------|-------------|
| [[Installation]] | Initial clone and dependency setup |
| [[Infrastructure-Setup]] | Docker, Chroma, Ollama, OpenRouter configuration |
| [[Troubleshooting]] | Symptom-based error resolution |
| [[Home]] | Wiki index |

---

*Document maintained by the hive-mcp team. Report issues at [hive-mcp/issues](https://github.com/hive-agi/hive-mcp/issues).*