wandb-hivemind 0.4.0
Syncs agentic coding sessions to Weights & Biases
Requires Python: >=3.13

# Hivemind

Daemon for syncing agentic coding sessions to Weights & Biases.

## Installation

```bash
# Via Homebrew (macOS)
brew install wandb/taps/hivemind

# Via pip
pip install hivemind
```

## Usage

```bash
# Run the daemon (watches for new sessions)
hivemind run

# Check status
hivemind status

# Pause syncing
hivemind pause

# Resume syncing
hivemind resume

# View logs
hivemind logs
hivemind logs -f  # Follow logs
```

## Authentication

```bash
# Login (auto-detects best method)
hivemind login

# Check authentication status
hivemind whoami

# Logout
hivemind logout
```

## Importing Existing Sessions

For development or initial setup, import existing sessions:

```bash
# Import ALL sessions found on disk
hivemind import

# Import sessions from the last 24 hours
hivemind import --since 1d

# Import sessions from the last 2 hours
hivemind import --since 2h

# Import sessions since a specific date
hivemind import --since 2024-01-15

# Dry run to preview what would be imported
hivemind import --dry-run

# Import from specific paths
hivemind import --path ~/projects/myapp

# Custom endpoint override
hivemind import --endpoint https://api.example.com
```

## Force Re-sync

If you need to re-import all sessions for a specific agent (e.g., after
fixing sync issues or to apply updated normalization):

```bash
# Re-sync all Cursor sessions
hivemind resync cursor

# Preview what would be deleted
hivemind resync cursor --dry-run

# Skip confirmation prompt
hivemind resync cursor --yes
```

**Supported agent types:** claude, claude_web, cursor, codex, gemini, opencode

**Warning**: This permanently deletes your session data from the server.
The data will be re-imported from your local session files.

**Rate limiting**: You can resync each agent type once per hour.

## Configuration

Configuration file: `~/.hivemind/config.toml`

```bash
# View current config and where values come from
hivemind config show

# Set endpoint (e.g., for QA testing)
hivemind config set server.endpoint https://hivemind.qa.wandb.tools

# Get a specific value
hivemind config get server.endpoint

# Reset to defaults
hivemind config reset

# Show config file path
hivemind config path
```

Example config file:

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

### Configuration Priority

Settings are resolved in this order (highest to lowest):

1. **Config file** (`~/.hivemind/config.toml`) - user's explicit preference
2. **Environment variable** (`HIVEMIND_ENDPOINT`) - for testing/CI overrides
3. **Default** (`https://hivemind.wandb.tools`)

The daemon automatically reloads when the config file changes.

### Environment Variables

- `HIVEMIND_ENDPOINT` - Backend API endpoint (overridden by config file)
- `HIVEMIND_IMPORT_SINCE` - Default --since filter for imports

## Troubleshooting

### Resync Issues

**"Cannot modify state: daemon is running"**
The resync command will automatically signal the running daemon. If you see this error, the signaling mechanism may have failed. Try stopping the daemon and running resync again.

**"Rate limit exceeded"**
You can only resync each agent type once per hour. Wait for the time shown in the error message.

**"Backend cleanup succeeded but local state update failed"**
Your server data has been deleted. The path to your state.json file is shown in the error. You can manually remove the sessions for that agent type, or simply restart the daemon - it will re-discover and re-sync all sessions.