Install Beads by hand

Beads is the task tracker your AI uses. Normally Claude installs it for you, following the tutorial. Use this guide only if that fails.

You will type a few commands into a terminal. Copy each command exactly, press Enter, and check the result.

Before you start

You have the Claude desktop app and your GitHub account (see the tutorial, steps 1 and 2).
You have been added to the life-itself GitHub organisation.
You know your team ID. It is your first name in lower case, unless you've been told otherwise.

Step 1. Open a terminal

Mac: press Command and Space together, type Terminal, and press Enter.
Windows: click Start, type PowerShell, and press Enter.

A terminal is a window where you type commands. Each command is a line of text, and you press Enter to run it.

Step 2. Install Beads

On a Mac, first check that Homebrew is installed. Homebrew is a tool that installs other tools for you.

brew --version

If you see a version number, go on. If you see "command not found", install Homebrew from brew.sh, then run the command again.

Then install Beads:

brew install beads

On Windows 11, run this one command in PowerShell:

irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex

Close PowerShell and open it again before the next step, so Windows can find the new tool.

Step 3. Check that Beads is installed

Run:

bd version

You should see a line that starts with bd version followed by a number. If you see "command not found", close the terminal, open it again, and retry. Still stuck? Message Asdra.

Step 4. Set up the planning folder

Go to the planning folder. If Claude cloned it for you, it is in ~/code/life-itself/planning (on Windows, your home folder then code\life-itself\planning):

cd ~/code/life-itself/planning

Then run:

bd bootstrap

Use bootstrap, not init. bootstrap copies the team's task list to your computer. init would start an empty list of your own.

Step 5. Set your name for Beads

Beads needs to know who you are, so that tasks you close show your name. Use your team ID from the start of this guide.

On a Mac, add a line to your shell settings, then open a new terminal:

echo 'export BEADS_ACTOR=yourid' >> ~/.zshenv

Replace yourid with your team ID. Open a new terminal window, then check:

echo $BEADS_ACTOR

On Windows, run this once in PowerShell, then open a new PowerShell window:

[Environment]::SetEnvironmentVariable("BEADS_ACTOR", "yourid", "User")

Check in the new window with echo $env:BEADS_ACTOR.

Step 6. Check that it works

In the planning folder, run:

bd ready

You should see a list of tasks that are ready to start. If the list is empty, Beads is working; there is just nothing ready right now.

Problems you may see

"command not found" for bd or brew. Close the terminal and open it again. If it still fails, you may have skipped the install step. Run it again.
A warning that .beads has permissions 0755. This is harmless, but fix it. In the planning folder, run chmod 700 .beads on a Mac. On Windows, ask Asdra.
echo $BEADS_ACTOR prints nothing. You didn't open a new terminal after Step 5. Open one and check again.
Anything with "dolt" in the error. Copy the full message and ask Claude what it means, or message Asdra.

Going further

Once Beads works, read the Beads guide to learn how to use it day to day. The official documentation is in the Beads repository. It is written for developers and covers more options than you need.