Hive Documentation

Complete reference for Hive — the native Rust desktop AI platform.

The Three Pillars

Multi-Agent System

Hive does not use a single AI agent. It uses a hierarchical swarm modeled on a beehive:

                    +-------------+
                    |    QUEEN    |   Meta-coordinator
                    |  (Planning) |   Goal decomposition
                    +------+------+   Budget enforcement
                           |          Cross-team synthesis
              +------------+------------+
              |            |            |
        +-----v----+ +----v-----+ +----v-----+
        |  TEAM 1  | |  TEAM 2  | |  TEAM 3  |
        | HiveMind | |Coordinator| |SingleShot|
        +----+-----+ +----+-----+ +----------+
             |             |
       +-----+-----+  +---+---+
       |     |     |  |       |
      Arch  Code  Rev Inv    Impl

Every team gets its own git worktree (swarm/{run_id}/{team_id}) for conflict-free parallel execution, merging back on completion.

AI Providers

15 providers with dynamic model fetching, automatic complexity-based routing, and fallback:

Features: dynamic model registry fetching from provider APIs, complexity classification, 14-entry fallback chain, per-model cost tracking, streaming support, budget enforcement.

Vector Memory & RAG

Hive maintains durable, searchable memory across conversations using LanceDB — a columnar vector database that runs embedded (no external server).

User query
    |
    v
EmbeddingProvider ─── OpenAI text-embedding-3-small (1536d)
    |                  or Ollama nomic-embed-text (768d)
    |                  with automatic fallback
    v
┌─────────────────────────────────────────────┐
│              LanceDB MemoryStore             │
│                                              │
│  chunks table          memories table        │
│  ┌──────────────┐      ┌──────────────────┐  │
│  │ source_file  │      │ content          │  │
│  │ content      │      │ category         │  │
│  │ embedding    │      │ importance       │  │
│  │ start_line   │      │ embedding        │  │
│  │ end_line     │      │ conversation_id  │  │
│  └──────────────┘      │ decay_exempt     │  │
│                        └──────────────────┘  │
└─────────────────────────────────────────────┘
    |                          |
    v                          v
Code search results       Recalled memories
    |                          |
    v                          v
# Retrieved Context       # Recalled Memories
(injected as system msg)  (dedicated system msg)

How It Works

Memory Categories

Memories are categorized for relevance scoring:

• UserPreference — Coding style, tooling choices, formatting preferences
• CodePattern — Recurring patterns and architectural decisions
• TaskProgress — What was done, what's pending
• Decision — Technical decisions and their rationale
• General — Catch-all for other durable insights

Injection Flow

On every message send: (1) Code chunks from the indexed workspace are injected into # Retrieved Context (curated by ContextEngine). (2) Recalled memories from previous conversations are injected as a separate # Recalled Memories system message with importance scores and categories. (3) Both are available to the AI alongside the conversation history.

Autonomous Skill Acquisition

Hive doesn't just execute what it already knows — it recognizes what it doesn't know and teaches itself. This is the closed-loop system that lets Hive grow its own capabilities in real time:

User request
    |
    v
Competence Detection ─── "I know this" ───> Normal execution
    |
    "I don't know this"
    |
    v
Search Skills / Sources ─── Found sufficient skill? ───> Install & use
    |
    Not found (or insufficient)
    |
    v
Knowledge Acquisition ───> Fetch docs, parse, synthesize
    |
    v
Skill Authoring Pipeline ───> Generate, security-scan, test, install
    |
    v
New skill available for future requests

[skill]
name = "my-review-skill"
description = "Reviews code for common bugs"
category = "CodeQuality"
enabled = true

[requirements]
capabilities = ["tool_use"]

[prompt]
template = "You are a code review assistant. Check for null pointer dereferences, off-by-one errors, and resource leaks."

[tools]
required = ["read_file"]

Personal Assistant

The assistant uses the same AI infrastructure as the development platform — same model routing, same security scanning, same learning loop.

Security & Privacy

Security is the foundation, not a feature bolted on. Every outgoing message is scanned. Every command is validated.

HiveShield — 4 Layers of Protection

Self-Improvement Engine

Hive gets smarter every time you use it. Entirely local. No data leaves your machine.

All learning data stored locally in SQLite (~/.hive/learning.db). Every preference is transparent, reviewable, and deletable.

Automation & Skills

Terminal & Execution

Remote Control

Hive can be controlled from any device on your network — phone, tablet, or another computer — via a built-in web server with real-time streaming.

Terminal Client (CLI)

A full-featured terminal client for interacting with Hive without the GUI:

hive chat                    # Interactive chat TUI with streaming
hive chat --model claude-3   # Chat with a specific model
hive models                  # List available AI models
hive status                  # Show account tier, usage, sync status
hive sync push               # Push data to cloud
hive sync pull               # Pull data from cloud
hive config                  # View all config
hive config key value        # Set a config value
hive login                   # Authenticate with Hive Cloud
hive remote                  # Show remote connection status

Built with Ratatui for a polished terminal UI with keyboard navigation, scrolling, and real-time streaming display.

Hive Cloud

Optional cloud services for users who want cross-device sync, cloud AI routing, and team features:

Cloud features are entirely optional. Hive works fully offline with local models.

P2P Federation

Hive instances can discover and communicate with each other over the network, enabling distributed swarm execution and shared learning.

Integrations

All integrations make real API calls — no stubs or simulated backends.

Blockchain / Web3

Persistence & Data Storage

All state persists between sessions. Nothing is lost on restart.

On startup, Hive automatically backfills JSON-only conversations into SQLite and builds FTS5 search indexes. Path traversal protection on all file operations. SQLite databases use WAL mode with NORMAL synchronous and foreign key enforcement.

Architecture — 19-Crate Workspace

hive/crates/
├── hive_app           Binary entry point — window, tray, build.rs (winres)
├── hive_ui            Workspace shell, chat service, learning bridge, title/status bars
├── hive_ui_core       Theme, actions, globals, sidebar, welcome screen
├── hive_ui_panels     All panel implementations (23 panels)
├── hive_core          Config, SecurityGateway, persistence (SQLite), Kanban, channels, scheduling
├── hive_ai            15 AI providers, capability-aware router, complexity classifier, context engine,
│                      RAG, embeddings (OpenAI + Ollama), LanceDB memory, background indexer
├── hive_agents        Queen, HiveMind, Coordinator, collective memory, MCP (19 tools),
│                      Universal Skills (SkillLoader + SkillExecutor, TOML persistence),
│                      competence detection, skill authoring
├── hive_shield        PII detection, secrets scanning, vulnerability assessment, access control
├── hive_learn         Outcome tracking, routing learner, preference model, prompt evolution
├── hive_assistant     Email, calendar, reminders, approval workflows, daily briefings
├── hive_fs            File operations, git integration, file watchers, search
├── hive_terminal      Command execution, Docker sandbox, browser automation, local AI detection
├── hive_docs          Document generation — CSV, DOCX, XLSX, HTML, Markdown, PDF, PPTX
├── hive_blockchain    EVM + Solana wallets, RPC config, token deployment with real JSON-RPC
├── hive_integrations  Google, Microsoft, GitHub, GitLab, Bitbucket, messaging, databases,
│                      cloud platforms, DevOps, knowledge bases, project management, OAuth2
├── hive_network       P2P federation, WebSocket transport, UDP discovery, peer registry, sync
├── hive_remote        Background daemon, WebSocket relay, QR pairing, web UI, REST API
├── hive_admin         Cloud admin TUI dashboard (6 tabs) [binary: hive-admin]
└── hive_cli           Terminal AI client (chat, sync, config, models) [binary: hive]

Dependency Flow

hive_app
  └── hive_ui
        ├── hive_ui_core
        ├── hive_ui_panels
        ├── hive_ai ──────── hive_core
        ├── hive_agents ──── hive_ai, hive_learn, hive_core
        ├── hive_shield
        ├── hive_learn ───── hive_core
        ├── hive_assistant ─ hive_core, hive_ai
        ├── hive_fs
        ├── hive_terminal
        ├── hive_docs
        ├── hive_blockchain
        ├── hive_integrations
        ├── hive_network
        └── hive_remote ──── hive_core, hive_ai, hive_agents, hive_network

hive_admin (standalone binary)
hive_cli   (standalone binary) ── hive_core

UI — 23 Panels

All panels are wired to live backend data. No mock data in the production path. 8 built-in themes with community voting and custom theme support.

Installation

Option 1: Download Pre-Built Binary (Recommended)

Grab the latest release for your platform from GitHub Releases.

# Ubuntu/Debian
sudo apt install mesa-vulkan-drivers vulkan-tools

# Fedora
sudo dnf install mesa-vulkan-drivers vulkan-tools

# Arch
sudo pacman -S vulkan-icd-loader vulkan-tools

Option 2: Build from Source

Requires Rust toolchain, protoc (Protocol Buffers compiler), and platform-specific build dependencies (see README for full details).

# Install protoc (required for gRPC)
# macOS: brew install protobuf
# Ubuntu: sudo apt install protobuf-compiler
# Windows: choco install protoc

git clone https://github.com/PatSul/Hive.git
cd Hive/hive
cargo build --release
cargo run --release

Run Tests

cd hive
cargo test --workspace

Configuration

On first launch, Hive creates ~/.hive/config.json. Add your API keys to enable cloud providers:

{
  "anthropic_api_key": "sk-ant-...",
  "openai_api_key": "sk-...",
  "google_api_key": "AIza...",
  "ollama_url": "http://localhost:11434",
  "lmstudio_url": "http://localhost:1234"
}

All keys are stored locally and never transmitted except to their respective providers. HiveShield scans every outbound request before it leaves your machine. Configure provider preferences, model routing rules, budget limits, and security policies through the Settings panel in the UI.