Hivemind

Distributed AI Swarm Runtime

Orchestrate multi-agent systems with a swarm execution model: tasks → DAG → parallel execution.

Install: PyPI package hivemind-ai · CLI hivemind

Quick start

1. Install (Python 3.12+):

pip install hivemind-ai
# or: uv add hivemind-ai

2. Set up API keys (pick one):

Store credentials in your OS keychain so you never re-enter them:

hivemind credentials set openai api_key      # prompts for value
hivemind credentials set anthropic api_key
hivemind credentials set github token
# or migrate from .env:
hivemind credentials migrate

Or use environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, GITHUB_TOKEN, etc. (see Credentials).

3. Create a project and run:

hivemind init
hivemind run "Summarize swarm intelligence in one paragraph."

4. Optional — shell completion:

# Bash: add to ~/.bashrc
eval "$(hivemind completion bash)"

# Zsh: add to ~/.zshrc
eval "$(hivemind completion zsh)"

Run from code

From config file:

from hivemind import Swarm

swarm = Swarm(config="hivemind.toml")
results = swarm.run("Analyze diffusion models and write a one-page summary.")

Explicit parameters:

from hivemind import Swarm

swarm = Swarm(worker_count=4, worker_model="gpt-4o-mini", planner_model="gpt-4o-mini", use_tools=True)
results = swarm.run("Your task here.")

Credentials are injected from the keyring (or env) when config is resolved—no code changes needed.

Credentials

API keys are not stored in config files. Use the credential store (OS keychain) or environment variables.

Providers: openai, anthropic, github, gemini, azure, azure_anthropic (keys: api_key, token, endpoint, deployment, api_version as applicable).

Example — export and source in a script:

eval "$(hivemind credentials export azure)"
hivemind run "Your task"

See Configuration and CLI for details.

CLI

Run hivemind --help or hivemind <command> --help for examples and options.

Features

• Planner → Scheduler → Executor → Agents — DAG-based execution with configurable parallelism
• Strategy-based planning — Auto-selected strategies (research, code, data science, document, experiment) or LLM fallback
• 120+ tools — Research, coding, data science, documents, experiments, memory; smart tool selection (top-k by similarity)
• TOML config — hivemind.toml / workflow.hivemind.toml; env > project > user > defaults
• Memory & knowledge graph — Episodic, semantic, research, artifact memory; summarization, namespaces, entity/relationship search
• Map-reduce runtime — swarm.map_reduce(dataset, map_fn, reduce_fn) using the worker pool
• Workflows — Define steps in workflow.hivemind.toml; run with hivemind workflow <name>; structured output self-correction (v1.7) retries with a correction prompt when JSON parsing fails
• Critic & agent messaging (v1.7) — Optional second-pass critic scores results and requests one retry; per-run message bus lets agents share discoveries via BROADCAST:
• Speculative pre-fetching (v1.7) — Pre-warm memory and tools for successor tasks while others run; reduces standing-up time
• Plugin ecosystem — Discover tools via entry_points (hivemind.plugins)
• Provider routing — OpenAI, Anthropic, Azure, Gemini, GitHub Models (Copilot) (provider:model or model name); 429 retry with backoff for GitHub rate limits
• Automatic model routing — planner = "auto" and worker = "auto" for cost/latency/quality-aware selection
• EventLog, replay, telemetry — Structured events for debugging and metrics

Architecture

    Planner
       ↓
    Scheduler
       ↓
    Executor
       ↓
    Agents  →  Tools  →  Memory  →  Knowledge Graph

Configuration

Priority: env > project config > user ~/.config/hivemind/config.toml > defaults.

Locations: ./hivemind.toml, ./workflow.hivemind.toml, ~/.config/hivemind/config.toml, or legacy .hivemind/config.toml.

Keep secrets out of TOML. Use hivemind credentials or environment variables for API keys. Non-secret settings (models, workers, paths) go in TOML.

Example hivemind.toml:

[swarm]
workers = 6
adaptive_planning = true
max_iterations = 10
critic_enabled = true
critic_roles = ["research", "analysis", "code"]
message_bus_enabled = true
prefetch_enabled = true

[models]
planner = "auto"
worker = "auto"

[memory]
enabled = true
store_results = true
top_k = 5

[tools]
enabled = ["research", "coding", "documents"]
top_k = 12

[telemetry]
enabled = true
save_events = true

[providers.azure]
endpoint = ""   # or use credentials store / env
deployment = ""

Env overrides: HIVEMIND_WORKER_MODEL, HIVEMIND_PLANNER_MODEL, HIVEMIND_EVENTS_DIR, HIVEMIND_DATA_DIR, plus provider keys. Full schema: docs/configuration.md, docs/providers.md.

Distributed mode (v1.10)

Run a controller and workers across processes or machines. Workers can be Python or Rust (hivemind-worker binary) for higher throughput.

# Redis + workers + controller (see examples/distributed/README.md)
docker compose up -d
uv run python examples/distributed/run_worker.py   # or Rust: HIVEMIND_WORKER_MODEL=github:gpt-4o ./worker/target/release/hivemind-worker
uv run python examples/distributed/run_controller.py "Your task" --parallel

Rust workers: set HIVEMIND_WORKER_MODEL=github:gpt-4o (or your model), HIVEMIND_PYTHON_BIN=.venv/bin/python, HIVEMIND_RPC_PORT=0 for multiple workers on one host. Credentials load from keychain in the subprocess.

Examples

Outputs under examples/output/. Run from project root when using script paths.

Documentation

Full docs (with versioning and dark mode): hivemind.rithul.dev. Source lives in website/docs/ and is built with Docusaurus.

Contributing

Contributions welcome. See CONTRIBUTING.md.

License

GPL-3.0-or-later — see LICENSE.