HiveMind CLI - Weights & Biases Documentation

The hivemind CLI manages the background daemon that syncs your coding sessions to HiveMind.

Installation

# Homebrew (macOS / Linux)
brew install wandb/tap/hivemind

# pip / uv
uv tool install wandb-hivemind

Quick start

hivemind login    # Authenticate with GitHub
hivemind start    # Start the daemon
hivemind status   # Check that it's running

Commands

Daemon management

Command	Description
`hivemind start`	Start the daemon
`hivemind stop`	Stop the daemon
`hivemind restart`	Stop and restart
`hivemind status`	Show PID, uptime, session counts
`hivemind logs`	View daemon logs
`hivemind doctor`	Find and fix common problems
`hivemind run`	Run in foreground (used by service managers)

Starting the daemon

hivemind start picks the right service manager for your platform and sets it up for you:

macOS: Homebrew services
Linux: systemd user service
Fallback: plain background process

# Normal start (uses your platform's service manager)
hivemind start

# Run in foreground for debugging
hivemind start --foreground

Checking status

hivemind status

This prints a table with the PID, uptime, tracked sessions, pending events, and log file path. Add --json for machine-readable output.

Viewing logs

# Recent logs
hivemind logs

# Follow in real-time
hivemind logs -f

# Last 50 lines
hivemind logs -n 50

Where the log file lives depends on your setup:

macOS (Homebrew): $(brew --prefix)/var/log/hivemind.log
macOS (other): ~/Library/Logs/hivemind/hivemind.log
Linux: ~/.local/state/hivemind/hivemind.log or syslog

Diagnosing issues

# See what's wrong
hivemind doctor

# Try to fix it automatically
hivemind doctor --fix

This checks for stale lock files, corrupted credentials, and service state mismatches.

Authentication

Command	Description
`hivemind login`	Log in with GitHub
`hivemind logout`	Remove stored credentials
`hivemind whoami`	Show who you’re logged in as

Sessions

Command	Description
`hivemind search`	Search sessions by keyword
`hivemind transcript`	View a session transcript
`hivemind import`	Bulk import existing sessions
`hivemind export`	Export session data
`hivemind resume`	Resume a previous session
`hivemind insights`	View session insights

Searching sessions

# Search by keyword
hivemind search "authentication bug"

# Filter by repo
hivemind search --repo myorg/myapp "refactor"

Importing sessions

If you started using HiveMind after you already had agent sessions on disk, import backfills them:

# Import sessions from the last 90 days (default)
hivemind import

# Import everything, no matter how old
hivemind config set import.max_age_days 0
hivemind import

Configuration

All config lives in ~/.hivemind/config.toml.

Command	Description
`hivemind config show`	Print all settings and where they came from
`hivemind config get KEY`	Get a single value
`hivemind config set KEY VALUE`	Set a value
`hivemind config add KEY VALUE`	Append to a list
`hivemind config reset KEY`	Reset to default
`hivemind config path`	Print the config file path

Config reference

Key	Type	Default	Description
`server.endpoint`	string	`https://hivemind.wandb.tools`	Backend API URL
`dev.debug`	bool	`false`	Enable debug logging
`web_sessions.enabled`	bool	`true`	Sync Claude web sessions
`web_sessions.poll_interval`	int	`1800`	Web session poll interval (seconds)
`import.max_age_days`	int	`90`	Max age for bulk import (0 = all)
`sessions.private`	bool	`false`	Make sessions private by default
`sessions.org_repos`	list	`[]`	Repos always visible to org
`sessions.private_repos`	list	`[]`	Repos always private

Example config

# ~/.hivemind/config.toml

[server]
endpoint = "https://hivemind.wandb.tools"

[dev]
debug = false

[web_sessions]
enabled = true
poll_interval = 1800

[import]
max_age_days = 90

[sessions]
private = false
org_repos = ["myorg/shared-project"]
private_repos = ["myorg/secret-project"]

API command

You can hit the backend API directly for debugging. The CLI handles auth for you.

# List sessions
hivemind api /sessions

# Get a specific session
hivemind api /sessions/SESSION_ID

# Query with parameters
hivemind api /sessions -q limit=10 -q user_id=abc123

# PUT request
hivemind api -X PUT /sessions/SESSION_ID/summary

# Raw JSON (no pretty-printing)
hivemind api /stats/active-users --raw

Flag	Description
`-X, --method`	HTTP method (GET, POST, PUT, DELETE, PATCH)
`-q, --query`	Query parameter as `key=value` (repeatable)
`-d, --data`	Request body (JSON string)
`--raw`	Skip pretty-printing, output raw JSON
`-v, --verbose`	Show request details

Troubleshooting

Problem	Fix
Daemon won’t start (“lock held”)	`hivemind doctor --fix`
Stale lock after a crash	`rm ~/.hivemind/daemon.lock`
”Not authenticated” after login	`hivemind doctor --fix && hivemind login`
Daemon not responding	`hivemind restart`
Permission errors on stop	`hivemind doctor && hivemind stop --force`
systemd fails to start	Check the logs: `journalctl --user -t hivemind -n 50`

File locations

File	What it’s for
`~/.hivemind/config.toml`	Configuration
`~/.hivemind/credentials.json`	Auth tokens
`~/.hivemind/state.json`	Sync state (which sessions have been uploaded)
`~/.hivemind/daemon.lock`	PID lock file

​Installation

​Quick start

​Commands

​Daemon management

​Starting the daemon

​Checking status

​Viewing logs

​Diagnosing issues

​Authentication

​Sessions

​Searching sessions

​Importing sessions

​Configuration

​Config reference

​Example config

​API command

​Troubleshooting

​File locations