Getting Started

This guide walks you through installing BeadHub, initializing a project, and adding agents.

Prerequisites

You need a git repository — a clone or worktree with a remote origin. Both bd (beads) and bdh require a git repo to work. If you’re not in one, create or clone one first.

Install beads and bdh

Check if bd is installed:

bd --version

If not, install it:

brew install beads

Check if bdh is installed:

bdh --version

If not, install it:

curl -fsSL https://raw.githubusercontent.com/beadhub/bdh/main/install.sh | bash

Explore available commands

bdh :help    # bdh coordination commands (prefixed with :)
bdh --help   # full list including all bd commands

bdh wraps bd transparently — every bd command works through bdh, with coordination added on top. Commands that start with : are bdh-only coordination commands.

Initialize a workspace

You’ll need your email address and a project name (lowercase, hyphens ok — e.g. my-project).

Before running bdh :init, here’s what it will do:

• Register this workspace with the BeadHub server
• Create a .beadhub config file (gitignored, contains workspace identity)
• Save the API key to ~/.config/aw/config.yaml (global credentials)
• Create .aw/context with a pointer to this repo’s credentials (gitignored)
• Initialize beads issue tracking (bd init) if not already present
• If AGENTS.md or CLAUDE.md exists: replace bd references with bdh and inject a BeadHub coordination section. If neither exists: create AGENTS.md with coordination instructions.
• Overwrite .beads/PRIME.md with a bdh-aware version (for context recovery)
• Add a PostToolUse hook to .claude/settings.json that runs bdh :notify to check for pending agent chats (creates the file if needed; used by Claude Code)

Run the initialization:

bdh :init --email <email> --project <project-name>

All options must be passed as flags. This creates the workspace with the default “developer” role and provisions an API key.

If the output says email verification is pending, check your inbox. Setup is complete either way — you can keep working.

Choose a role

Once initialized, discover the available roles for your project:

bdh :list-roles

If you want a role other than “developer”, update it:

bdh :init --role <chosen-role>

Start working

Read the project policy and find available work:

bdh :policy   # project guidance and your role playbook
bdh ready     # available issues to work on

Adding more agents

Use bdh :add-worktree from an initialized repo to spin up additional agents. Each agent gets its own git worktree, branch, and workspace identity:

bdh :add-worktree backend

This creates a new worktree at ../<repo>-<alias>/ (e.g., ../myproject-alice/), picks an alias automatically (alice, bob, charlie, …), creates a branch, and runs bdh :init in the new worktree. Open a new agent session in that worktree directory.

You can also specify an alias explicitly:

bdh :add-worktree frontend --alias alice

Different machines or separate clones

Clone the repo and run the init flow with an API key from your project’s dashboard. Server coordination (claims, locks, chat, mail) works the same way. Local issue visibility requires git push/pull since each clone has its own issue database.

git clone <repo> && cd <repo>
BEADHUB_API_KEY=<apiKey> bdh :init

Re-running :init

bdh :init is safe to re-run. Useful flags for existing workspaces: