bds-setup

Beads Setup

One-time per-repository setup for the beads-starter workflow.

On Activation

Walk the user through the steps below. Run the read-only checks (steps 1 and 5) without asking. Ask for confirmation only before commands that change the machine or the repository: installing bd (step 2) and initializing (step 4). For those, show the commands first, then ask before executing.

Steps

1. Check for bd

Run:

command -v bd && bd version

If bd is already installed and reports a version, skip to step 3. Otherwise proceed to step 2.

2. Install bd (if missing)

The beads team recommends Homebrew. Show the user the options and ask which they want:

Homebrew (macOS / Linux, recommended)

brew install beads

npm (Node.js users)

npm install -g @beads/bd

Install script (other platforms)

curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

For Windows, Arch AUR, go install, or building from source, point them to https://github.com/gastownhall/beads/blob/main/docs/getting-started/installation.md.

3. Determine the prefix

The prefix is used for issue IDs (e.g., MYPROJ-42). Default suggestion: the current directory's basename. Do not ask about it separately; propose it in the step 4 confirmation.

4. Initialize

Show all five commands with the proposed prefix filled in, then ask in one question whether to run them with that prefix:

bd init --shared-server --prefix <PREFIX> --skip-agents --skip-hooks
bd config set no-git-ops true
bd config set dolt.local-only true
bd config unset sync.remote
if git remote get-url origin >/dev/null 2>&1; then bd dolt remote remove origin; fi

If the user answers with a different prefix, substitute it and run the commands.

5. Verify

Run:

bd ready --json

A successful exit (even with empty JSON output) means setup is complete.

6. Brief the user on expected warnings

After setup, the following warnings are normal under this preset and should not trigger action: