Getting Started

Prerequisites

• An MCP-compatible client — Claude Code, Codex CLI, Gemini CLI, GitHub Copilot, Cursor, Windsurf, or any other MCP host
• An Obsidian vault (or any directory of Markdown files) — see Vault Structure for the expected layout
• Optional for worker delegation: any OpenAI-compatible /v1 endpoint — a hosted service or a runtime on your own machine. You need its base URL, a credential if it requires one, and a model id. Hive names no provider.

Install

One command. No cloning, no venv, no config files.

Use user scope

Always register Hive at user scope (not project scope) so it works across all your projects. That’s the whole point — one vault, every project.

• Claude Code: -s user flag
• Gemini CLI: -s user flag
• Codex CLI / Copilot / OpenCode: config files are already user-level (~/.codex/config.toml, ~/.config/opencode/opencode.jsonc) or can be added to VS Code user settings

Claude Code

claude mcp add -s user hive -- uvx --upgrade hive-vault

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

Gemini CLI

gemini mcp add -s user hive-vault uvx -- --upgrade hive-vault

Copilot (VS Code)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "enabled": true
    }
  }
}

The --upgrade flag ensures you always get the latest version from PyPI on each session start. uvx handles the Python environment automatically.

Updating a persistent installation

The uvx configurations above resolve the current release for each new session. If you use a persistent installation for daemon mode, upgrade it deliberately:

# Linux / macOS
uv tool upgrade hive-vault

# Windows (the version is optional; omitted selects the latest PyPI release)
hive self-upgrade [version]

On Windows, self-upgrade builds the new release beside the active files and atomically switches the managed runtime, so it does not modify files held by a running Hive process. Open a new terminal after the first managed upgrade so the launcher added to your user PATH is available. Start a new MCP session after any upgrade; an existing session keeps its current server process.

First Query

Once registered, your AI assistant can use Hive tools. Try asking:

“Use vault_list to see my vault”

The assistant will call vault_list() and list all projects with file counts and available shortcuts.

Configure Vault Path

By default, Hive looks for your vault at ~/Projects/knowledge. If this path doesn’t exist, vault tools will return a helpful error with setup instructions — the server still starts, so worker tools remain available.

To point Hive to your vault:

Claude Code

claude mcp add -s user hive -e VAULT_PATH=/path/to/your/vault -- uvx --upgrade hive-vault

Codex CLI

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "/path/to/your/vault"

Gemini CLI

gemini mcp add -s user -e VAULT_PATH=/path/to/your/vault hive-vault uvx -- --upgrade hive-vault

Copilot (VS Code)

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

OpenCode

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/path/to/your/vault"
      },
      "enabled": true
    }
  }
}

Configure Worker (Optional)

To enable task delegation, point Hive at one OpenAI-compatible endpoint with HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY and HIVE_WORKER_MODEL. Without a base URL the worker stays disabled and delegate_task tells the host to handle the task itself:

Claude Code

# Export HIVE_WORKER_API_KEY from your secret store first.
claude mcp add -s user hive \
  -e VAULT_PATH=/path/to/your/vault \
  -e HIVE_WORKER_BASE_URL=https://api.your-provider.example/v1 \
  -e HIVE_WORKER_API_KEY="$HIVE_WORKER_API_KEY" \
  -e HIVE_WORKER_MODEL=<model-id> \
  -- uvx --upgrade hive-vault

Codex CLI

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "/path/to/your/vault"
HIVE_WORKER_BASE_URL = "https://api.your-provider.example/v1"
HIVE_WORKER_API_KEY = "<your-key>"
HIVE_WORKER_MODEL = "<model-id>"

Gemini CLI

# Export HIVE_WORKER_API_KEY from your secret store first.
gemini mcp add -s user \
  -e VAULT_PATH=/path/to/your/vault \
  -e HIVE_WORKER_BASE_URL=https://api.your-provider.example/v1 \
  -e HIVE_WORKER_API_KEY="$HIVE_WORKER_API_KEY" \
  -e HIVE_WORKER_MODEL=<model-id> \
  hive-vault uvx -- --upgrade hive-vault

Copilot (VS Code)

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/path/to/your/vault",
        "HIVE_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<your-key>",
        "HIVE_WORKER_MODEL": "<model-id>"
      }
    }
  }
}

OpenCode

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/path/to/your/vault",
        "HIVE_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<your-key>",
        "HIVE_WORKER_MODEL": "<model-id>"
      },
      "enabled": true
    }
  }
}

See Configuration for all environment variables.

Verify

Run a health check:

“Use vault_health to check my vault”

You should see project counts, file counts, and staleness metrics for each project in your vault.

Next Steps

• Use Cases — real-world workflows with Hive
• Configuration — full environment variable reference
• Vault Tools — all vault tools
• Worker Tools — task delegation and worker status
• Vault Structure — how to organize your vault
• Troubleshooting — common issues and fixes