---
title: Getting Started
description: Install and configure Hive in under a minute.
---

import { Tabs, TabItem } from '@astrojs/starlight/components';

## Prerequisites

- An MCP-compatible client — [Claude Code](https://docs.anthropic.com/en/docs/build-with-claude/claude-code/overview), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), [Cursor](https://cursor.com/), [Windsurf](https://windsurf.com/), or any other MCP host
- An [Obsidian](https://obsidian.md/) vault (or any directory of Markdown files) — see [Vault Structure](/hive/guides/vault-structure/) for the expected layout
- **Optional for worker delegation:**
  - [Ollama](https://ollama.com/download) running locally — pull a model with `ollama pull qwen2.5-coder:7b`
  - [OpenRouter](https://openrouter.ai/) account — create an API key at [openrouter.ai/keys](https://openrouter.ai/keys) (free tier available)

## Install

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

:::tip[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:** config files are already user-level (`~/.codex/config.toml`) or can be added to VS Code user settings
:::

<Tabs syncKey="client">
  <TabItem label="Claude Code">
    ```bash
    claude mcp add -s user hive -- uvx --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Codex CLI">
    Add to `~/.codex/config.toml`:
    ```toml
    [mcp_servers.hive-vault]
    command = "uvx"
    args = ["--upgrade", "hive-vault"]
    ```
  </TabItem>
  <TabItem label="Gemini CLI">
    ```bash
    gemini mcp add -s user hive-vault uvx -- --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Copilot (VS Code)">
    Add to `.vscode/mcp.json` in your project:
    ```json
    {
      "servers": {
        "hive-vault": {
          "command": "uvx",
          "args": ["--upgrade", "hive-vault"]
        }
      }
    }
    ```
  </TabItem>
</Tabs>

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

## 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`. To change it:

<Tabs syncKey="client">
  <TabItem label="Claude Code">
    ```bash
    claude mcp add -s user hive -e VAULT_PATH=/path/to/your/vault -- uvx --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Codex CLI">
    ```toml
    [mcp_servers.hive-vault]
    command = "uvx"
    args = ["--upgrade", "hive-vault"]

    [mcp_servers.hive-vault.env]
    VAULT_PATH = "/path/to/your/vault"
    ```
  </TabItem>
  <TabItem label="Gemini CLI">
    ```bash
    gemini mcp add -s user -e VAULT_PATH=/path/to/your/vault hive-vault uvx -- --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Copilot (VS Code)">
    ```json
    {
      "servers": {
        "hive-vault": {
          "command": "uvx",
          "args": ["--upgrade", "hive-vault"],
          "env": {
            "VAULT_PATH": "/path/to/your/vault"
          }
        }
      }
    }
    ```
  </TabItem>
</Tabs>

## Configure Worker (Optional)

To enable task delegation to cheaper models:

<Tabs syncKey="client">
  <TabItem label="Claude Code">
    ```bash
    claude mcp add -s user hive \
      -e VAULT_PATH=/path/to/your/vault \
      -e HIVE_OLLAMA_ENDPOINT=http://your-ollama:11434 \
      -e OPENROUTER_API_KEY=sk-or-... \
      -- uvx --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Codex CLI">
    ```toml
    [mcp_servers.hive-vault]
    command = "uvx"
    args = ["--upgrade", "hive-vault"]

    [mcp_servers.hive-vault.env]
    VAULT_PATH = "/path/to/your/vault"
    HIVE_OLLAMA_ENDPOINT = "http://your-ollama:11434"
    OPENROUTER_API_KEY = "sk-or-..."
    ```
  </TabItem>
  <TabItem label="Gemini CLI">
    ```bash
    gemini mcp add -s user \
      -e VAULT_PATH=/path/to/your/vault \
      -e HIVE_OLLAMA_ENDPOINT=http://your-ollama:11434 \
      -e OPENROUTER_API_KEY=sk-or-... \
      hive-vault uvx -- --upgrade hive-vault
    ```
  </TabItem>
  <TabItem label="Copilot (VS Code)">
    ```json
    {
      "servers": {
        "hive-vault": {
          "command": "uvx",
          "args": ["--upgrade", "hive-vault"],
          "env": {
            "VAULT_PATH": "/path/to/your/vault",
            "HIVE_OLLAMA_ENDPOINT": "http://your-ollama:11434",
            "OPENROUTER_API_KEY": "sk-or-..."
          }
        }
      }
    }
    ```
  </TabItem>
</Tabs>

See [Configuration](/hive/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](/hive/guides/use-cases/) — real-world workflows with Hive
- [Configuration](/hive/configuration/) — full environment variable reference
- [Vault Tools](/hive/tools/vault/) — all vault tools
- [Worker Tools](/hive/tools/worker/) — task delegation and routing
- [Vault Structure](/hive/guides/vault-structure/) — how to organize your vault
- [Troubleshooting](/hive/guides/troubleshooting/) — common issues and fixes
