From 67d51ec335e7b7694596a1e7f524764be209839d Mon Sep 17 00:00:00 2001 From: vanpelt Date: Tue, 2 Jun 2026 17:12:02 -0400 Subject: [PATCH 1/4] Add W&B HiveMind product documentation Port the HiveMind docs (a shared dashboard for AI coding sessions) into the Mintlify site, following the same product structure as Weave: - hivemind.mdx: product landing page with install tabs, doc cards, and the supported-agents table - hivemind/{features,permissions,cli,bots,mdm}.mdx: ported from the HiveMind source docs, with GitHub callouts converted to Mintlify components and internal links rewritten to /hivemind/* - product-hivemind.mdx: product dropdown redirect stub - icons/HiveMind.svg: honeycomb glyph for the home-page product card - index.mdx: add a W&B HiveMind ProductCard to the Weights & Biases group - docs.json: register the W&B HiveMind menu item and dropdown entry (en) - AGENTS.md: note the new /hivemind/ directory Validated with mint dev and mint broken-links (no broken links). Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 1 + docs.json | 16 +- hivemind.mdx | 75 +++++++ hivemind/bots.mdx | 457 +++++++++++++++++++++++++++++++++++++++ hivemind/cli.mdx | 234 ++++++++++++++++++++ hivemind/features.mdx | 72 ++++++ hivemind/mdm.mdx | 104 +++++++++ hivemind/permissions.mdx | 166 ++++++++++++++ icons/HiveMind.svg | 5 + index.mdx | 12 +- product-hivemind.mdx | 4 + 11 files changed, 1143 insertions(+), 3 deletions(-) create mode 100644 hivemind.mdx create mode 100644 hivemind/bots.mdx create mode 100644 hivemind/cli.mdx create mode 100644 hivemind/features.mdx create mode 100644 hivemind/mdm.mdx create mode 100644 hivemind/permissions.mdx create mode 100644 icons/HiveMind.svg create mode 100644 product-hivemind.mdx diff --git a/AGENTS.md b/AGENTS.md index e19b67129f..37aff96862 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,6 +56,7 @@ Key directories: - `/platform/` - W&B Platform features and hosting documentation. - `/models/` - W&B Models documentation. - `/weave/` - W&B Weave documentation. +- `/hivemind/` - W&B HiveMind documentation (shared dashboard for AI coding sessions). - `/inference/` - Serverless Inference documentation. - `/serverless-training/` - Serverless Training documentation (Serverless RL and Serverless SFT subcategories; formerly Serverless RL / W&B Training). - `/snippets/` - Reusable content snippets. diff --git a/docs.json b/docs.json index be0d312467..4e5da74f01 100644 --- a/docs.json +++ b/docs.json @@ -95,7 +95,8 @@ "group": "Weights & Biases", "pages": [ "product-models", - "product-weave" + "product-weave", + "product-hivemind" ] }, { @@ -783,6 +784,17 @@ } ] }, + { + "item": "W&B HiveMind", + "pages": [ + "hivemind", + "hivemind/features", + "hivemind/permissions", + "hivemind/cli", + "hivemind/bots", + "hivemind/mdm" + ] + }, { "item": "Serverless Inference", "pages": [ @@ -6836,4 +6848,4 @@ "stylesheet": "/css/styles.css" }, "theme": "aspen" -} \ No newline at end of file +} diff --git a/hivemind.mdx b/hivemind.mdx new file mode 100644 index 0000000000..b8c1f4a875 --- /dev/null +++ b/hivemind.mdx @@ -0,0 +1,75 @@ +--- +title: "W&B HiveMind" +description: "A shared dashboard for your team's AI coding sessions, synced automatically by a lightweight daemon." +mode: wide +--- + +W&B HiveMind is a shared dashboard for AI coding sessions. A lightweight daemon runs on each developer's machine, watches for coding agent activity, and sends session transcripts to [hivemind.wandb.tools](https://hivemind.wandb.tools). + +Coding agents like Claude Code, Codex, Cursor, Gemini, and OpenCode all write transcripts to the local filesystem as they work. The HiveMind daemon wakes up every 30 seconds, checks for new activity, and uploads anything it finds. There's nothing to configure per agent. If the agent writes transcripts, HiveMind picks them up. + +## Get started + + + + ```bash + brew install wandb/tap/hivemind + hivemind start + ``` + + The daemon starts in the background and authenticates via GitHub. That's it. + + + If you don't have Homebrew, install via `uv`: + + ```bash + uv tool install wandb-hivemind + hivemind install-service + hivemind start + ``` + + `install-service` sets up a systemd user service so the daemon starts automatically on login. + + + +Once the daemon is running, open any supported coding agent and start working. Within 30 seconds your session appears on the [dashboard](https://hivemind.wandb.tools). You can watch sessions in real time, review past conversations, and dig into individual tool calls. + +## Explore the docs + + + + Tour the dashboard, session detail views, and the GitHub and Slack integrations. + + + + Control who can see your sessions, configure visibility, and set up SSO. + + + + Manage the daemon, search sessions, and configure HiveMind from the command line. + + + + Push sessions from CI, cloud agents, and headless environments with token or OIDC auth. + + + + Roll HiveMind out across a fleet with JAMF, Intune, and other MDM tools. + + + +## Supported agents + +HiveMind picks up transcripts from the coding agents you already use, with no per-agent setup. + +| Agent | Transcript source | +| ----------- | ------------------------------------- | +| Claude Code | `~/.claude/projects/` JSONL files | +| Codex | `~/.codex/` session logs | +| Cursor | SQLite databases in Cursor's app data | +| Gemini CLI | `~/.gemini/` session history | +| OpenCode | `~/.opencode/` session files | + +## The HiveMind agent + +HiveMind also installs a coding agent skill. Type `@hivemind` inside a Claude Code session to ask questions about past coding sessions: what you worked on last week, how a bug was fixed, or where a particular change was made. It searches across your team's session history and pulls the answer into your current conversation. diff --git a/hivemind/bots.mdx b/hivemind/bots.mdx new file mode 100644 index 0000000000..08af5a369a --- /dev/null +++ b/hivemind/bots.mdx @@ -0,0 +1,457 @@ +--- +title: "Bots and service accounts" +description: "Push sessions to HiveMind from CI, cloud agents, and headless environments using static tokens or OIDC federation." +--- + +Bots, including CI jobs, cloud agents, scheduled tasks, and headless scripts, push sessions to HiveMind without an interactive `hivemind login`. There are two ways to authenticate one, and the choice determines who the resulting sessions belong to. + +## Identity: PAT or service account? + +| Token | Acts as | Good for | +| ------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- | +| **Personal access token (PAT)** | You, the user who minted it. Sessions land in your account. | Personal scripts, your laptop, one-off bots only you care about. | +| **Service account (SA)** | Its own `sa_*` identity. Sessions are owned by the SA, not by you. | Shared CI, cloud agents, anything that needs to outlive your tenure. | + +Mint a PAT under **Settings > Personal Access Tokens** and inject it as `HIVEMIND_TOKEN`, the same env var the daemon uses for any static token. Your org admin can disable PAT authentication org-wide or restrict it to `write` scope only, so check that policy before depending on one. + +Service accounts have their own `sa_*` identity and scoped tokens. With OIDC federation, the workload swaps a short-lived ID token from a trusted provider for a HiveMind token at runtime, so there's no static secret to rotate. Everything else on this page is about service accounts. Pick a PAT if you want the session under your own name, or an SA if you want it under a dedicated bot identity. + +## Pick an auth method + +| Where the bot runs | Auth | +| ----------------------------------- | ------------------------------- | +| GitHub Actions | GitHub Actions OIDC | +| GitHub Copilot cloud agent | GitHub Actions OIDC via MCP env | +| Kubernetes pod | Projected service account token | +| Modal Function | Modal OIDC | +| Anything else (cron, VM, fly.io) | Static `HIVEMIND_TOKEN` | + +Prefer OIDC when it's available. Policy is checked against verified claims on every exchange, and there's nothing for you to rotate. + +## Identity providers + +Configure these per service account in **Admin > Service Accounts**. + + +The HiveMind server fetches your issuer's OIDC discovery document and JWKS to verify token signatures, so the **issuer URL has to be reachable from the HiveMind server over the internet**. GitHub Actions and Modal already are. A self-hosted IdP or a Kubernetes cluster on a private network is not, so you'll need to expose the issuer endpoint (TLS, public DNS, no auth required for `.well-known/openid-configuration` and the JWKS URI) before the exchange can succeed. + + +### GitHub Actions + +| Field | Value | +| -------- | ------------------------------------------------------- | +| Issuer | `https://token.actions.githubusercontent.com` | +| Audience | Your HiveMind URL (e.g. `https://hivemind.wandb.tools`) | +| Selector | `repo:OWNER/REPO` | + +Put branch, environment, and `pull_request` constraints in the CEL policy, not the selector. Your workflow needs `id-token: write` so the runner will mint an ID token (see the [Pattern A example](#pattern-a-ci-agents-you-launch-yourself) below for the full job structure). + +### Kubernetes + +| Field | Value | +| -------- | --------------------------------------- | +| Issuer | Your cluster's issuer URL | +| Audience | The audience set on the projected token | +| Selector | `system:serviceaccount:NAMESPACE:NAME` | + +Mount a projected service account token whose audience matches your HiveMind server: + +```yaml +spec: + volumes: + - name: hivemind-token + projected: + sources: + - serviceAccountToken: + path: token + audience: https://hivemind.wandb.tools + expirationSeconds: 3600 + containers: + - name: hivemind + volumeMounts: + - name: hivemind-token + mountPath: /var/run/secrets/hivemind + readOnly: true +``` + +The mount plus `path: token` resolves to `/var/run/secrets/hivemind/token`, which is where the daemon reads from by default. Override with `HIVEMIND_OIDC_TOKEN_FILE` if you need a different path. + + +Don't reuse `/var/run/secrets/kubernetes.io/serviceaccount/token`. Its audience is the Kubernetes API and the exchange will fail. You need a separate projected token with the HiveMind audience. + + +### Modal + +| Field | Value | +| -------- | ------------------------------------------ | +| Issuer | `https://oidc.modal.com` | +| Audience | `https://oidc.modal.com` (locked by Modal) | +| Selector | `modal:workspace_id:ac-12345abcd` | + +Modal injects `MODAL_IDENTITY_TOKEN` once at container start and never rotates it. Modal mints ~48h ID tokens, so our handler clamps the resulting JWT to the 24h ceiling, long enough to cover a full-timeout Modal Function without a mid-run refresh. See [Token lifecycle](#token-lifecycle) below. + +Environment, app, and function names go in the CEL policy. + +### Generic OIDC + +Any provider with an OIDC discovery document, including in-house IdPs, build systems, and anything that mints JWTs. + +| Field | Value | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| Issuer | Your provider's issuer URL | +| Audience | Defaults to your HiveMind server (`https://hivemind.wandb.tools` on managed). Override if your provider issues tokens with a different audience. | +| Selector | Whatever `sub` claim you want to match on | + +To feed an ID token to the daemon, write it to a file and point `HIVEMIND_OIDC_TOKEN_FILE` at the path: + +```bash +echo "$MY_OIDC_TOKEN" > /tmp/hivemind-oidc-token +HIVEMIND_OIDC_TOKEN_FILE=/tmp/hivemind-oidc-token hivemind start +``` + +If `HIVEMIND_OIDC_TOKEN_FILE` is unset, the daemon falls back to `/var/run/secrets/hivemind/token`, the same code path Kubernetes projected tokens use. The daemon reads the file and posts the contents to the backend, which routes by the token's `iss` claim. + +For tokens your provider rotates, rewrite the file in place. The daemon re-reads it on every refresh, so an updated file picks up automatically the next time the JWT nears expiry. + +### Static token + +When OIDC isn't an option, mint a service-account token in the dashboard and inject it as `HIVEMIND_TOKEN`. No exchange, no policy, so treat it like any other secret. + +Pick an expiration when you create the token: + +| Option | When to use | +| ------- | ------------------------------------ | +| `30d` | Short-lived bots you'll rotate often | +| `90d` | Sensible default for CI | +| `6m` | Long enough to forget about | +| `1y` | Annual rotation cadence | +| `never` | Avoid unless you rotate out-of-band | + + +Always set an expiration. A leaked token with no expiry is the worst kind to find six months later. The dashboard shows a per-token expiration badge so you can rotate ahead of time. + + +## Scopes + +There are two scopes, `read` and `write`, and the same set applies whether you authenticate via OIDC or a static token. + +| Scope | Grants | +| ------- | --------------------------------------------- | +| `write` | Upload sessions and source entries | +| `read` | Query sessions, events, and stats via the API | + +Most bots only need `write`. Add `read` for analytics jobs or agents that look at past sessions to inform new runs. A `read`-only token fits dashboards and exporters that should never push. + +## Set one up + +1. Open **Admin > Service Accounts > New service account**. +2. Pick a provider. Issuer is pre-filled for the built-in ones. For Generic OIDC, paste your provider's issuer URL. +3. Set the selector and scopes, and save. + +Then wire the bot up with whichever pattern below matches your runtime. Every exchange does an `(issuer, selector)` lookup to find the SA, then verifies the token's signature and audience against the configured provider. See [Token lifecycle](#token-lifecycle) for how the resulting JWT is sized and rotated. + +## Advanced: CEL policies + +A CEL policy further restricts which tokens get exchanged, on top of the issuer and selector match. It's most useful for **shared platforms** like GitHub Actions: `https://token.actions.githubusercontent.com` is the issuer for every workflow on GitHub, so the policy is where you pin to specific repos, branches, or workflows. The same applies to Modal, where one issuer serves every workspace. + +A GitHub Actions policy pinned to one workflow on `main`: + +```cel +claims.repository == "octo-org/octo-repo" && +claims.ref == "refs/heads/main" && +claims.workflow_ref.startsWith("octo-org/octo-repo/.github/workflows/release.yml") +``` + +A Modal policy pinned to one app and environment: + +```cel +claims.environment_name == "main" && +claims.app_name == "agent-runner" +``` + +For a private issuer you control end-to-end (an in-house IdP, a Kubernetes cluster only your team has access to), you can usually skip the policy entirely. The selector match is enough. + +## Token lifecycle + +What happens after the daemon makes its first exchange. + +### JWT lifetime + +The HiveMind JWT the daemon receives tracks the ID token's `exp` claim, clamped to **[1h, 24h]**: + +| ID token `exp − now` | JWT TTL | +| -------------------- | ------------- | +| Less than 1h | 1h (floor) | +| 1h to 24h | Matches `exp` | +| More than 24h | 24h (ceiling) | + +The floor keeps short runner tokens (GitHub Actions hands out ~10min ID tokens) from causing constant refresh churn. The ceiling caps the blast radius of a leaked JWT. In between, we honor what the issuer signed for. A 4-hour Modal Function with a 4-hour identity token gets a 4-hour JWT, so the daemon doesn't have to refresh mid-run. + +### Rotation + +Roughly five minutes before the JWT expires, the daemon refreshes by re-reading the ID token source and re-running the exchange. Whether refresh succeeds depends on the source: + +| Source | Refresh behavior | +| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GitHub Actions | Fetches a fresh ID token from the runner endpoint on each refresh: fresh `jti`, always succeeds. | +| Kubernetes projected token | Kubelet rewrites the file in place at ~80% of the token TTL: fresh `iat`/`exp` produce a fresh replay key. | +| `HIVEMIND_OIDC_TOKEN_FILE` (generic) | Whoever wrote the file is responsible for rewriting it before the JWT expires. The same file means replay rejection. | +| Modal `MODAL_IDENTITY_TOKEN` | Static for the container lifetime, so it doesn't rotate. Modal mints ~48h ID tokens, so the JWT clamps to the 24h ceiling and covers a full-timeout Modal Function (Modal's own max is 24h) without ever needing to refresh. | +| Static `HIVEMIND_TOKEN` | No exchange to refresh. The token is the JWT. Lives until you rotate it manually. | + +If a refresh attempt sees the same ID token it already exchanged (same `jti` or the same synthesized replay key), the daemon's client-side guard short-circuits the call and falls back to the cached JWT until it actually expires. After that point sync pauses until a fresh ID token is available. + +### JTI replay protection + +Every ID token is exchanged exactly once. The backend stores the `(issuer, jti)` pair in Redis with a 24h TTL and rejects any subsequent exchange that matches. + +A few edge cases worth knowing: + +- **Tokens without `jti`** (notably vanilla Kubernetes projected service account tokens, which carry `iss/sub/aud/exp/iat` but no `jti` claim) are handled automatically. The server derives a stable replay key by hashing the canonical full set of verified claims, keyed by the matched issuer and audience. Kubelet's in-place rotation always produces a fresh `iat`/`exp`, so legitimate rotations get a fresh key and succeed while replays of the same physical token still collide and are blocked. +- **Generic OIDC providers** that follow OIDC Core typically include `jti`. If yours doesn't, the synthesis path catches it as long as the token carries `iat`, `sub`, and `exp`. Tokens missing all three are rejected. +- **The replay window is per-issuer**: two different issuers can mint tokens with the same `jti` string and they won't collide. + +## Pattern A: CI agents you launch yourself + +When you control the runner loop (you install the agent, you call it, you tear it down), run the daemon alongside the agent with `hivemind start` and `hivemind stop`. Sessions stream live, and the daemon does a final catch-up pass on shutdown. + +A complete GitHub Actions job. The `id-token: write` permission is what lets the runner mint an OIDC token. The daemon exchanges it for a HiveMind JWT on its own, so you don't need a static `HIVEMIND_TOKEN` secret: + +```yaml +jobs: + run-agent: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + + - uses: astral-sh/setup-uv@v7 + + - name: Install hivemind + run: | + uv venv --python 3.13 "$HOME/.hivemind-venv" + uv pip install --python "$HOME/.hivemind-venv/bin/python" wandb-hivemind + echo "$HOME/.hivemind-venv/bin" >> "$GITHUB_PATH" + + - name: Start hivemind daemon + run: hivemind start + + - name: Run Claude Code + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + - name: Stop hivemind daemon + if: always() + run: hivemind stop || true +``` + +`hivemind start` launches the daemon in the background. `hivemind stop` sends SIGTERM and waits up to 10s for a final catch-up pass so the agent's last message makes it to the dashboard. The `if: always()` guard makes sure `stop` runs even when the agent step fails, so failed runs still get uploaded. + +For agents that write to a non-default home dir (Codex, custom Cursor paths), set the home env var on the `Start hivemind daemon` step. The daemon inherits it and watches the right place: + +```yaml +- name: Start hivemind daemon + env: + CODEX_HOME: /tmp/codex-home + run: hivemind start +``` + +### Lighter alternative: import after the run + +If you don't want a background daemon, `hivemind import --all` uploads everything in one shot at the end of the job: + +```yaml +- name: Upload sessions to HiveMind + run: hivemind import --all +``` + +It exits non-zero if any session fails to upload, or if it finds zero sessions (override with `--allow-empty`), so the step itself is the assertion. + +| Flag | Purpose | +| ----------------------------------- | -------------------------------------------------------- | +| `--all` | Search all known agent dirs (default: current repo only) | +| `--since 1d` / `--since 2026-01-15` | Limit by modification time | +| `--agents claude,cursor` | Restrict to specific agents | +| `--path ` | Add an explicit search path (repeatable) | +| `--dry-run` | Show what would be uploaded | +| `--allow-empty` | Don't fail when zero sessions are found | + +The same pattern works outside CI. Drop `hivemind import --since 1h` into a shell wrapper or a cron entry. It's idempotent, so re-running is safe. + +## Pattern B: Long-running container (Docker sidecar) + +When the agent runs continuously and you want sessions to stream live, run hivemind as a sidecar. It watches the agent's session directory read-only and uploads on a timer. + +The agent writes JSONL into a shared named volume. The sidecar reads the same volume and uploads: + +```yaml +services: + agent: + image: node:20-slim + working_dir: /workspace + volumes: + - claude-sessions:/root/.claude + - ./workspace:/workspace + environment: + - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} + command: > + sh -c " + npm install -g @anthropic-ai/claude-code && + claude -p 'Hello, world!' + " + depends_on: + hivemind: + condition: service_healthy + + hivemind: + image: ghcr.io/wandb/hivemind:latest + volumes: + - claude-sessions:/watch/.claude:ro + - hivemind-state:/home/hivemind/.hivemind + environment: + - HIVEMIND_ENDPOINT=${HIVEMIND_ENDPOINT} + - HIVEMIND_TOKEN=${HIVEMIND_TOKEN} + - HIVEMIND_WATCH_PATHS=/watch/.claude + healthcheck: + test: + [ + "CMD", + "hivemind", + "health", + "-q", + "--state-dir", + "/home/hivemind/.hivemind", + ] + interval: 10s + timeout: 3s + retries: 3 + start_period: 5s + restart: unless-stopped + stop_grace_period: 30s + +volumes: + claude-sessions: + hivemind-state: +``` + +Run it: + +```bash +export HIVEMIND_TOKEN= +export HIVEMIND_ENDPOINT=https://hivemind.wandb.tools +docker compose up +``` + + +On platforms that issue OIDC tokens (GitHub Actions, Modal, Kubernetes), drop `HIVEMIND_TOKEN` and pass the platform's OIDC env vars to the sidecar instead. + + +| Provider | Inject | +| -------------- | ------------------------------------------------------------------ | +| GitHub Actions | `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | +| Modal | `MODAL_IDENTITY_TOKEN` | +| Kubernetes | The mounted token file (default `/var/run/secrets/hivemind/token`) | + +The 30-second `stop_grace_period` matters: it gives the sidecar time to flush the final upload batch when Compose tears the stack down. + +## Pattern C: GitHub Copilot cloud agent (MCP server) + +For runners where you _don't_ control the loop, like the GitHub Copilot cloud agent, register hivemind as an MCP server. Copilot's runtime spawns it at session start and tears it down at session end, so the daemon's lifecycle matches the agent's. + +### 1. Add the MCP server + +In **repo Settings > Copilot > MCP configuration**: + +```json +{ + "mcpServers": { + "hivemind": { + "type": "local", + "command": "hivemind", + "args": ["mcp"], + "tools": ["status"], + "env": { + "ACTIONS_ID_TOKEN_REQUEST_URL": "COPILOT_MCP_OIDC_REQUEST_URL", + "ACTIONS_ID_TOKEN_REQUEST_TOKEN": "COPILOT_MCP_OIDC_REQUEST_TOKEN" + } + } + } +} +``` + +Two things have to happen on the runner before Copilot spawns the MCP subprocess: + +1. **`hivemind` has to be on `PATH`**, because Copilot resolves the `command` value against `PATH`. +2. **The OIDC request env vars have to be re-exported under the `COPILOT_MCP_` prefix.** Copilot only forwards env vars with that prefix into MCP subprocesses, so the daemon won't see GitHub's `ACTIONS_ID_TOKEN_REQUEST_*` env vars unless you copy them over. + +Both belong in `.github/workflows/copilot-setup-steps.yml`, which Copilot runs automatically before launching the agent: + +```yaml +name: Copilot Setup Steps +on: workflow_dispatch + +permissions: {} + +jobs: + copilot-setup-steps: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # required for OIDC exchange + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: astral-sh/setup-uv@v7 + + - name: Install hivemind onto PATH + run: | + uv venv --python 3.13 "$HOME/.hivemind-venv" + uv pip install --python "$HOME/.hivemind-venv/bin/python" wandb-hivemind + echo "$HOME/.hivemind-venv/bin" >> "$GITHUB_PATH" + + - name: Forward Copilot runtime env to MCP servers + run: | + echo "COPILOT_MCP_OIDC_REQUEST_URL=$ACTIONS_ID_TOKEN_REQUEST_URL" >> "$GITHUB_ENV" + echo "COPILOT_MCP_OIDC_REQUEST_TOKEN=$ACTIONS_ID_TOKEN_REQUEST_TOKEN" >> "$GITHUB_ENV" +``` + +If OIDC passthrough isn't an option in your environment, fall back to a static token: mint one in the dashboard, store it as `COPILOT_MCP_HIVEMIND_TOKEN` under **Settings > Environments > copilot**, and reference it from the MCP config (Copilot requires the `COPILOT_MCP_` prefix on every secret): + +```json +"env": { + "HIVEMIND_TOKEN": "COPILOT_MCP_HIVEMIND_TOKEN" +} +``` + +### 2. Flush on shutdown + +Copilot kills the MCP subprocess when the agent finishes, so the daemon may have entries it hasn't uploaded yet. Add a session-end hook that calls `hivemind flush` to drain those before the runner is torn down. Drop this at `.github/hooks/hooks.json`: + +```json +{ + "version": 1, + "hooks": { + "sessionEnd": [ + { + "type": "command", + "bash": "hivemind flush || true", + "timeoutSec": 60, + "comment": "Drain pending uploads before the Copilot runner is torn down." + } + ] + } +} +``` + +`hivemind flush` blocks until in-flight uploads finish, or until the 60s timeout. The `|| true` keeps a flush error from failing the agent. + +## What's next + +- [Permissions & privacy](/hivemind/permissions): how service-account sessions inherit visibility. +- [HiveMind CLI](/hivemind/cli): full `hivemind import` documentation. diff --git a/hivemind/cli.mdx b/hivemind/cli.mdx new file mode 100644 index 0000000000..e32b58aca9 --- /dev/null +++ b/hivemind/cli.mdx @@ -0,0 +1,234 @@ +--- +title: "HiveMind CLI" +description: "The hivemind CLI manages the background daemon that syncs your coding sessions to HiveMind." +--- + +The `hivemind` CLI manages the background daemon that syncs your coding sessions to HiveMind. + +## Installation + +```bash +# Homebrew (macOS / Linux) +brew install wandb/tap/hivemind + +# pip / uv +uv tool install wandb-hivemind +``` + +## Quick start + +```bash +hivemind login # Authenticate with GitHub +brew services start wandb/tap/hivemind # 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 + +The daemon picks the right service manager for your platform: + +- **macOS**: Homebrew services (`brew services start wandb/tap/hivemind`) +- **Linux**: systemd user service (`systemctl --user start hivemind`) +- **Fallback**: plain background process + +```bash +# Normal start (uses your platform's service manager) +hivemind start + +# Run in foreground for debugging +hivemind start --foreground +``` + +#### Checking status + +```bash +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 + +```bash +# 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 + +```bash +# 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 + +```bash +# 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: + +```bash +# 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 + +```toml +# ~/.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. + +```bash +# 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` | +| Homebrew service not responding | `brew services restart wandb/tap/hivemind` | +| 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 | diff --git a/hivemind/features.mdx b/hivemind/features.mdx new file mode 100644 index 0000000000..029cf35c38 --- /dev/null +++ b/hivemind/features.mdx @@ -0,0 +1,72 @@ +--- +title: "Features" +description: "A tour of what HiveMind shows you and how to get the most out of it." +--- + +A tour of what HiveMind shows you and how to get the most out of it. + +## Dashboard pages + +### Overview + +Your home screen. Three tabs give you different angles on recent activity: + +- **Activity**: a feed of your AI coding sessions from the past week. +- **My Stats**: your personal streak, top repositories, rank, and a calendar heatmap of when you've been working with agents. +- **Team Stats**: adoption metrics across the organization, including active users, activity over time, and aggregate streaks. + +### Live view + +A real-time view of coding sessions happening right now. The sidebar lists active sessions with status indicators: green for actively working, blue for waiting on user input, and gray for ended. Pick a session to watch its event timeline stream in as it happens. + +You can filter by repository to focus on a specific project, or switch to "My Sessions" to see only your own. + +### Insights + +Repository-level suggestions extracted from your team's coding patterns. HiveMind analyzes sessions for a given repo and surfaces conventions, common pitfalls, and workflow patterns it noticed across multiple sessions. + +Each suggestion includes a confidence level, the evidence behind it, and a ready-to-use snippet you can apply to your project's `CLAUDE.md` (or similar config) via the CLI. You can dismiss suggestions you don't find useful. + +### Leaderboard + +A ranked view of activity across your team. The top 15 users are shown alongside a breakdown of which repositories and agents are seeing the most use. When you filter to a specific repo, the view shifts to show session duration distribution for that project. + +### Repositories + +An overview of all repositories with agent activity. Each repo card shows total session count, cumulative duration, and how many people have been working in it. Click through to see detailed activity for a specific repo. + +### Sessions + +The main session browser. You can view sessions grouped by branch or as a flat list, and filter by user, team, repository, time range, agent type, minimum turn count, or minimum duration. + +#### Session detail + +Click into any session to see the full conversation. The detail page has several tabs: + +- **Timeline**: the full event stream, grouped into turns. Tool calls, file edits, and agent reasoning are all shown inline. +- **Diff**: a combined view of all file changes the agent made during the session. You can copy or download the diff. +- **Transcript**: the session as a readable document. You can copy it to your clipboard or download it as Markdown, JSONL, or ATIF format. Transcript settings let you filter which event types to include and toggle verbose mode. + +##### Search + +Use the search bar (Cmd+K / Ctrl+K) to find sessions by content, file names, or keywords. Results link directly to the matching session, and when the match is inside a specific message, the page scrolls to that point in the timeline. + +##### Sub-agents + +When a session spawns sub-agents (common with Claude Code's Agent tool), HiveMind captures those child sessions and merges their file operations into the parent session's diff view. A badge on the session header shows how many sub-agent sessions ran and which models they used. + +## Integrations + +### GitHub App + +The [HiveMind GitHub App](https://github.com/apps/w-b-hivemind) connects your GitHub repositories to HiveMind. Once installed, it does two things: + +**PR comments**: when a pull request is opened on a branch where agent sessions occurred, HiveMind posts a comment summarizing the AI-assisted work, including which sessions contributed, who ran them, and links back to the full transcripts. The comment updates automatically as new sessions are uploaded or the PR is updated. + +**Repository visibility gating**: the GitHub App is also what powers [repository-level access controls](/hivemind/permissions#repository-visibility-gating). It lets HiveMind verify which users have write access to which repos, so admins can restrict session visibility accordingly. + +### Slack + +When someone pastes a HiveMind session link in Slack, it unfurls into a rich preview showing the session title, who ran it, which agent and model were used, duration, and token count. If the session is linked to a pull request, the preview includes the PR status. + +This works automatically once a Slack workspace admin installs the [HiveMind Slack app](https://slack.com/marketplace/A0AM3CCURAT-hivemind). No per-user setup is needed, so anyone in the workspace sees unfurls for links they have access to. diff --git a/hivemind/mdm.mdx b/hivemind/mdm.mdx new file mode 100644 index 0000000000..8bff887ca3 --- /dev/null +++ b/hivemind/mdm.mdx @@ -0,0 +1,104 @@ +--- +title: "Deploy with MDM" +description: "Roll HiveMind out across a fleet of macOS devices with JAMF, Intune, and other MDM tools using a signed, notarized .pkg." +--- + +For fleet rollouts (JAMF, Intune, Mosyle, Kandji, Workspace ONE), HiveMind ships as a signed, notarized macOS `.pkg`. It's a single file you push as a payload, with no interactive installer and no per-machine setup. This page walks through JAMF. The same `.pkg` works in any MDM that can deploy a package. + +## Get the package + +Download `hivemind-darwin-arm64.pkg` from the latest [release](https://github.com/wandb/homebrew-taps/releases). The package is signed and notarized by **Weights and Biases, Inc.** (Team ID `5DTHBP38WM`), so Gatekeeper accepts it on any managed Mac. + +It installs to a system location and registers a per-user background service: + +| Path | What it is | +| ------------------------------------------------ | -------------------------------- | +| `/usr/local/hivemind/bin/hivemind` | The daemon binary | +| `/Library/LaunchAgents/com.wandb.hivemind.plist` | LaunchAgent that runs the daemon | +| `/etc/paths.d/hivemind` | Puts the binary on `PATH` | +| `/usr/local/hivemind/uninstall.sh` | Bundled uninstaller | + +The daemon runs as a background LaunchAgent in each logged-in user's session. Because the plist lives in the admin-owned `/Library/LaunchAgents/` (not a user's home folder), the install works unattended and the daemon starts at the next login for any user on the machine, with no login script or policy trigger needed. + +## Deploy with JAMF + +1. **Upload the package.** In JAMF Pro, go to **Settings > Computer Management > Packages** and add `hivemind-darwin-arm64.pkg`. +2. **Create a policy.** Under **Computers > Policies**, create a new policy with the **Packages** payload and add the HiveMind package with action **Install**. +3. **Set a trigger.** **Recurring Check-in** (or **Enrollment Complete** for new devices) installs it across the fleet without user interaction. +4. **Scope it.** Target the smart or static computer group you want to cover, then save. + +That's the whole rollout. On a machine where a user is already logged in, the daemon starts immediately. Otherwise it starts at their next login. + +## Auto-upgrade is on by default + +Once installed via the package, the daemon keeps itself up to date. It checks for new releases on a timer and, when one is available, verifies the download's signature and Team ID before swapping the binary in place and restarting itself. You don't need to re-push the package for upgrades. Deploy once and devices stay current. + + +In-place upgrades need the daemon's user to be able to write the install dir. When a user is logged in at install time the installer assigns it to them. An unattended push (nobody logged in) instead makes the dir **admin-group-writable**, so the primary user on a managed Mac, typically a local admin, still auto-upgrades with no further action. Only when the daemon runs as a **non-admin** user does it need a hand: `hivemind doctor` flags it and `hivemind doctor --fix` grants access. You can also skip auto-upgrade and manage versions by re-pushing the `.pkg`. + + +To turn auto-upgrade off and manage versions yourself, set the daemon to notify-only or off on each device: + +```bash +hivemind config set daemon.auto_upgrade off +``` + +| Value | Behavior | +| -------- | --------------------------------------------------------------------- | +| `apply` | Download and install upgrades automatically (default for the package) | +| `notify` | Log that an upgrade is available, but don't install | +| `off` | Never check for upgrades | + +## Suppress the background-item notification + +On macOS 13 and later, the first time the daemon's LaunchAgent loads, the user sees a **"Background items added"** notification. To pre-approve HiveMind across the fleet so this never appears, push a **Service Management - Managed Login Items** configuration profile that trusts the vendor. + +In JAMF, create a configuration profile with the **Service Management - Managed Login Items** payload and add a rule of one of these types: + +| Rule type | Value | Notes | +| ------------------- | -------------------- | ------------------------------------------------------------ | +| **Team Identifier** | `5DTHBP38WM` | Trusts everything signed by Weights and Biases, most stable | +| **Label** | `com.wandb.hivemind` | Pins to this specific background service | + +Scope the profile to the same computer group as the install policy. With it in place, the daemon's LaunchAgent loads silently and the user is never prompted. + +## Authentication + +The daemon authenticates each user against GitHub, trying silent methods first (SSH key signature, git credential helper, `gh` CLI) and falling back to a browser login only when none is available. On a typical developer Mac with GitHub already set up, no action is needed. For headless or shared machines, see [Bots & service accounts](/hivemind/bots) for token-based auth. + +## Uninstall + +The package bundles an uninstaller. Push it as a JAMF policy with a **Files and Processes > Execute Command** payload, or run it directly: + +```bash +sudo /usr/local/hivemind/uninstall.sh +``` + +It removes the binary, the LaunchAgent, and the package receipt, while preserving each user's local state and credentials in `~/.hivemind/`. To remove that too: + +```bash +rm -rf ~/.hivemind +``` + +## Verify a rollout + +On a sample device after the push: + +```bash +# Binary present +ls -l /usr/local/hivemind/bin/hivemind + +# LaunchAgent registered for the logged-in user +launchctl print "gui/$(id -u)/com.wandb.hivemind" | head -5 + +# Full health check +hivemind doctor +``` + +If the `launchctl print` step reports "Could not find service," the user hasn't logged in since install yet. Wait for their next login, or run `hivemind doctor` for a fuller diagnosis. `hivemind doctor` also confirms auto-upgrade can write the install dir. If it can't (a non-admin user on an unattended install), `hivemind doctor --fix` repairs it. + +## What's next + +- [HiveMind CLI](/hivemind/cli): daemon management, logs, and `hivemind doctor`. +- [Bots & service accounts](/hivemind/bots): token auth for headless and shared machines. +- [Permissions & privacy](/hivemind/permissions): who can see your team's sessions. diff --git a/hivemind/permissions.mdx b/hivemind/permissions.mdx new file mode 100644 index 0000000000..7cdfbff7bf --- /dev/null +++ b/hivemind/permissions.mdx @@ -0,0 +1,166 @@ +--- +title: "Permissions & privacy" +description: "Control who can see your HiveMind sessions, configure default and per-repo visibility, and set up SSO." +--- + +## Default visibility + +New accounts default to **private** sessions, so only you can see them. You can change this any time on your [settings page](https://hivemind.wandb.tools/settings), or share an individual session from the session detail page. + +Once you've set your visibility to **Repository**, newly created sessions are shared with other members of your GitHub organization when they occurred within a repository associated with your organization that you have write access to. Changing this setting does not retroactively update existing sessions. For example: + +| Detected origin | Effect | +| --------------------------- | ------------------------------------------------------------------------------------ | +| github.com/wandb/hivemind | Shared with members of the wandb GitHub org that have write access to wandb/hivemind | +| github.com/vanpelt/dotfiles | Only visible to you | +| _none_ | Only visible to you | + +### Repository visibility gating + +When sessions are shared with your organization, each member only sees sessions for repositories their GitHub account has write access to. You always see your own sessions regardless. Write access is verified through the [HiveMind GitHub App](https://github.com/apps/w-b-hivemind), which must be installed on at least one of your linked GitHub organizations. + +### Workspaces + +Every session belongs to one workspace. Workspaces are tied to your GitHub org membership: + +- **Organization workspaces** are GitHub organizations with the [HiveMind GitHub App](https://github.com/apps/w-b-hivemind) installed. +- **Personal workspaces** get created automatically for sessions that don't match any registered org. + +You can switch between your organization and personal workspaces by clicking the profile avatar in the upper right corner of the navigation bar. Sessions from your personal workspace appear in the organization workspace but are only visible to you, as indicated by the eye icon. + +## Device-local configuration + +To make all coding sessions go to your **personal workspace** instead of using the git repository to determine visibility, run the following: + +```bash +hivemind config set sessions.private true +``` + + +This setting only applies to the machine you ran the command on. There is also a global configuration setting you can configure on your [settings page](https://hivemind.wandb.tools/settings) to default to private sessions globally. + + +| Setting | Effect | +| -------------------------- | ---------------------------------------------------------- | +| `sessions.private = false` | Sessions in org GitHub repos visible to your org (default) | +| `sessions.private = true` | All sessions visible only to you | + +### Per-repo overrides + +Sometimes the global setting isn't granular enough. You might want most sessions private, but still share work on your team's main repo. Or you might keep things open by default, but lock down a sensitive project. + +That's what `org_repos` and `private_repos` are for. + +#### Always share a repo (allowlist) + +Repos in `org_repos` are visible to your org even when `sessions.private` is `true`: + +```bash +hivemind config add sessions.org_repos "myorg/shared-project" +``` + +#### Always hide a repo (denylist) + +Repos in `private_repos` are private no matter what. This wins over everything else: + +```bash +hivemind config add sessions.private_repos "myorg/secret-project" +``` + +Repo names are case-insensitive. You can use `org/repo` or `host/org/repo`. + +#### Example config + +```toml +# ~/.hivemind/config.toml + +[sessions] +private = true # Default: keep sessions private +org_repos = ["myorg/open-source"] # Exception: this repo is always shared +private_repos = ["myorg/secret-proj"] # This repo is ALWAYS private +``` + +## Global configuration + +If you want all sessions to default to being private and associated with your personal workspace, you can change the global default settings from your [settings page](https://hivemind.wandb.tools/settings). + +### How the rules stack up + +When HiveMind decides whether a session is visible: + +1. `private_repos`: if the repo is here, it's private. Full stop. +2. `org_repos`: if the repo is here, it's shared with members of the org who have write access to the repo. +3. `sessions.private`: the fallback for a device, defaults to false. +4. **Global setting**: if a repo was not made public via `org_repos` and the global setting is private, it's private. + +## Single sign-on (SSO) + +Organization admins can require members to authenticate through their company's identity provider (IdP) instead of relying on GitHub credentials alone. This is configured from the [Admin > Authentication](https://hivemind.wandb.tools/admin/authentication) page. + +### How it works + +HiveMind supports OpenID Connect (OIDC), which is compatible with most identity providers (Okta, Azure AD, Google Workspace, and others). An admin registers their IdP's issuer URL and client ID in the admin panel. Once configured, the admin can optionally enforce SSO so that all members must sign in through the IdP to access organization data. + +HiveMind uses PKCE (Proof Key for Code Exchange) for the OAuth flow, so a client secret is only needed if your IdP doesn't support public clients. When provisioning HiveMind as a service provider, choose "Native App" if your IdP asks. + +### What members see + +When SSO enforcement is turned on, members who haven't authenticated via the IdP see a prompt to log in through SSO before they can view any organization sessions. Members can still access their personal workspace without SSO. + +### SCIM provisioning + +If your organization uses SCIM, HiveMind can automatically sync your IdP's user directory. Members removed from the IdP lose access to the organization workspace. SCIM is configured from the [Admin > SCIM](https://hivemind.wandb.tools/admin/provisioning) page. + +## Authentication + +HiveMind attempts to authenticate automatically using your GitHub identity. The daemon tries these methods in order, picking the first one that works: + +1. **SSH signature**: signs a challenge with your SSH key (silent, most common). +2. **GitHub credential helper**: pulls a token from your git credential manager (silent). +3. **GitHub CLI**: uses your `gh auth` token (silent). +4. **Browser OAuth**: opens your default browser to log in via GitHub or your org's SSO (interactive, used when no silent credential is available). +5. **Device OAuth**: prints a code to enter at GitHub or your org's SSO identity provider, for headless machines without a usable browser. + + +When the credential helper or GitHub CLI is used, your GitHub PAT is passed to the HiveMind server to federate your identity. This is similar to the [AWS STS service](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) for identity federation. We do not store your credentials and take special care to not log them. They are only used in the federation request to confirm your identity. + + +To log in: + +```bash +hivemind login +``` + +To check who you're logged in as: + +```bash +hivemind whoami +``` + +### Workload identity federation + +For CI runners and other ephemeral environments, the daemon can exchange a short-lived OIDC ID token from a trusted provider for a HiveMind token at runtime, so there's no static secret to manage: + +- **GitHub Actions**: the daemon presents the workflow's OIDC token. The HiveMind app verifies the repo, ref, and workflow claims and mints a daemon token. +- **Modal**: Modal-issued OIDC tokens are exchanged the same way, attributing sessions to a configured service account. +- **Generic OIDC**: any IdP that can produce a project-scoped ID token (Kubernetes projected service-account tokens, custom OIDC providers) can be wired up by pointing `HIVEMIND_OIDC_TOKEN_FILE` at a file the IdP keeps refreshed. + +See [Bots & service accounts](/hivemind/bots) for the full OIDC federation setup. + +### Personal access tokens + +Where federation isn't available (one-off scripts, third-party CI you don't fully control), mint a token under **Settings > Personal Access Tokens** and export it as `HIVEMIND_TOKEN`. Org admins can disable PATs or restrict them to `write` scope from the admin panel. + +### Scopes + +Every HiveMind token carries a `scopes` claim (`read`, `write`, or both) that controls what API calls it can make. Write lets the daemon upload sessions and emit telemetry. Read lets you view other users' sessions in the dashboard and CLI. + +| Login method | Default scope | +| ---------------------------------------- | --------------------------------------------- | +| Browser OAuth (GitHub or SSO) | `read + write` | +| Device OAuth | `read + write` | +| Personal access token | Chosen at creation, subject to admin policy | +| Service account / federated OIDC | Whatever the service account was created with | +| SSH signature, credential helper, gh CLI | `write` only when your org enforces SSO | + +When SSO is required on your org, the three silent direct-credential methods (SSH, credential helper, gh CLI) only mint write-only tokens. The daemon can keep uploading sessions, but reading other users' data requires completing an SSO browser login (`hivemind login --method sso_browser`). diff --git a/icons/HiveMind.svg b/icons/HiveMind.svg new file mode 100644 index 0000000000..ef5f4059a0 --- /dev/null +++ b/icons/HiveMind.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/index.mdx b/index.mdx index e61aa55cb4..32ce3d24f3 100644 --- a/index.mdx +++ b/index.mdx @@ -11,7 +11,7 @@ import {ProductCard} from "/snippets/ProductCard.jsx";

Develop AI models and ship LLM applications with the W&B platform for experiment tracking, evaluation, and observability.

-
+
Manage AI models in your code with tracing, output evaluation, cost estimates, and a playground to compare large language models (LLMs) and settings. + + + Share your team's AI coding sessions on one dashboard. A lightweight daemon syncs transcripts from Claude Code, Codex, Cursor, and more, with insights, leaderboards, and GitHub and Slack integrations. +
## Powered by CoreWeave diff --git a/product-hivemind.mdx b/product-hivemind.mdx new file mode 100644 index 0000000000..dc442bd249 --- /dev/null +++ b/product-hivemind.mdx @@ -0,0 +1,4 @@ +--- +title: "W&B HiveMind" +url: "/hivemind" +--- From b4d728b632a60d880620a95699a73c4b0cb1e4ea Mon Sep 17 00:00:00 2001 From: vanpelt Date: Tue, 2 Jun 2026 17:30:39 -0400 Subject: [PATCH 2/4] HiveMind docs: use hivemind start instead of brew/systemd service commands hivemind start now sets up the platform service manager itself, so users don't run brew services or install-service directly. - Linux quickstart: drop hivemind install-service (start does it) - CLI quickstart: hivemind start instead of brew services start - Troubleshooting: hivemind restart instead of brew services restart Co-Authored-By: Claude Opus 4.8 (1M context) --- hivemind.mdx | 3 +-- hivemind/cli.mdx | 14 +++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/hivemind.mdx b/hivemind.mdx index b8c1f4a875..edfe95f47f 100644 --- a/hivemind.mdx +++ b/hivemind.mdx @@ -24,11 +24,10 @@ Coding agents like Claude Code, Codex, Cursor, Gemini, and OpenCode all write tr ```bash uv tool install wandb-hivemind - hivemind install-service hivemind start ``` - `install-service` sets up a systemd user service so the daemon starts automatically on login. + `hivemind start` sets up a systemd user service for you, so the daemon starts automatically on login. diff --git a/hivemind/cli.mdx b/hivemind/cli.mdx index e32b58aca9..efadb3f643 100644 --- a/hivemind/cli.mdx +++ b/hivemind/cli.mdx @@ -18,9 +18,9 @@ uv tool install wandb-hivemind ## Quick start ```bash -hivemind login # Authenticate with GitHub -brew services start wandb/tap/hivemind # Start the daemon -hivemind status # Check that it's running +hivemind login # Authenticate with GitHub +hivemind start # Start the daemon +hivemind status # Check that it's running ``` ## Commands @@ -39,10 +39,10 @@ hivemind status # Check that it's running #### Starting the daemon -The daemon picks the right service manager for your platform: +`hivemind start` picks the right service manager for your platform and sets it up for you: -- **macOS**: Homebrew services (`brew services start wandb/tap/hivemind`) -- **Linux**: systemd user service (`systemctl --user start hivemind`) +- **macOS**: Homebrew services +- **Linux**: systemd user service - **Fallback**: plain background process ```bash @@ -220,7 +220,7 @@ hivemind api /stats/active-users --raw | 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` | -| Homebrew service not responding | `brew services restart wandb/tap/hivemind` | +| 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` | From 55403fb8afe604935267323e91ff36c68ccc7cf4 Mon Sep 17 00:00:00 2001 From: vanpelt Date: Tue, 2 Jun 2026 17:31:29 -0400 Subject: [PATCH 3/4] HiveMind docs: drop "What's next" sections Mintlify already renders next/prev page links, so the manual cross-link lists at the end of mdm and bots are redundant. Co-Authored-By: Claude Opus 4.8 (1M context) --- hivemind/bots.mdx | 5 ----- hivemind/mdm.mdx | 6 ------ 2 files changed, 11 deletions(-) diff --git a/hivemind/bots.mdx b/hivemind/bots.mdx index 08af5a369a..64d5ba5236 100644 --- a/hivemind/bots.mdx +++ b/hivemind/bots.mdx @@ -450,8 +450,3 @@ Copilot kills the MCP subprocess when the agent finishes, so the daemon may have ``` `hivemind flush` blocks until in-flight uploads finish, or until the 60s timeout. The `|| true` keeps a flush error from failing the agent. - -## What's next - -- [Permissions & privacy](/hivemind/permissions): how service-account sessions inherit visibility. -- [HiveMind CLI](/hivemind/cli): full `hivemind import` documentation. diff --git a/hivemind/mdm.mdx b/hivemind/mdm.mdx index 8bff887ca3..2d784e5934 100644 --- a/hivemind/mdm.mdx +++ b/hivemind/mdm.mdx @@ -96,9 +96,3 @@ hivemind doctor ``` If the `launchctl print` step reports "Could not find service," the user hasn't logged in since install yet. Wait for their next login, or run `hivemind doctor` for a fuller diagnosis. `hivemind doctor` also confirms auto-upgrade can write the install dir. If it can't (a non-admin user on an unattended install), `hivemind doctor --fix` repairs it. - -## What's next - -- [HiveMind CLI](/hivemind/cli): daemon management, logs, and `hivemind doctor`. -- [Bots & service accounts](/hivemind/bots): token auth for headless and shared machines. -- [Permissions & privacy](/hivemind/permissions): who can see your team's sessions. From 4be9798c8b87b828b8a7876e74c6909a010ac311 Mon Sep 17 00:00:00 2001 From: vanpelt Date: Tue, 2 Jun 2026 17:35:11 -0400 Subject: [PATCH 4/4] HiveMind docs: add Pi and Copilot CLI to supported agents Co-Authored-By: Claude Opus 4.8 (1M context) --- hivemind.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/hivemind.mdx b/hivemind.mdx index edfe95f47f..98e4347377 100644 --- a/hivemind.mdx +++ b/hivemind.mdx @@ -6,7 +6,7 @@ mode: wide W&B HiveMind is a shared dashboard for AI coding sessions. A lightweight daemon runs on each developer's machine, watches for coding agent activity, and sends session transcripts to [hivemind.wandb.tools](https://hivemind.wandb.tools). -Coding agents like Claude Code, Codex, Cursor, Gemini, and OpenCode all write transcripts to the local filesystem as they work. The HiveMind daemon wakes up every 30 seconds, checks for new activity, and uploads anything it finds. There's nothing to configure per agent. If the agent writes transcripts, HiveMind picks them up. +Coding agents like Claude Code, Codex, Copilot, Cursor, Gemini, OpenCode, and Pi all write transcripts to the local filesystem as they work. The HiveMind daemon wakes up every 30 seconds, checks for new activity, and uploads anything it finds. There's nothing to configure per agent. If the agent writes transcripts, HiveMind picks them up. ## Get started @@ -61,13 +61,15 @@ Once the daemon is running, open any supported coding agent and start working. W HiveMind picks up transcripts from the coding agents you already use, with no per-agent setup. -| Agent | Transcript source | -| ----------- | ------------------------------------- | -| Claude Code | `~/.claude/projects/` JSONL files | -| Codex | `~/.codex/` session logs | -| Cursor | SQLite databases in Cursor's app data | -| Gemini CLI | `~/.gemini/` session history | -| OpenCode | `~/.opencode/` session files | +| Agent | Transcript source | +| ----------- | --------------------------------------- | +| Claude Code | `~/.claude/projects/` JSONL files | +| Codex | `~/.codex/` session logs | +| Copilot CLI | `~/.copilot/session-state/` event logs | +| Cursor | SQLite databases in Cursor's app data | +| Gemini CLI | `~/.gemini/` session history | +| OpenCode | `~/.opencode/` session files | +| Pi | `~/.pi/agent/sessions/` JSONL files | ## The HiveMind agent