Getting started

This page takes you from installing Builder to your first crew. Like a bead, it describes Builder as it is designed to work, and Builder is not available to install yet.

What you need

• A Mac, and a terminal you are comfortable opening.
• Claude Code, signed in to your Claude account. Every Builder session is a conversation with Claude in a terminal.

Homebrew installs anything else Builder needs.

Install

Builder installs from a terminal with a single Homebrew command, which this page will give once Builder is public. The install puts everything Builder owns under one folder, ~/builder unless you choose another, and it finishes by telling you where to meet the steward.

Meet the steward

Start a session in the steward's folder:

cd ~/builder/steward
claude

The steward is the first session you meet, and it owns no project of its own. It asks what you want to build, then gets the smallest real version of that running with you.

Your first crew

The steward builds your first project by creating a crew for it: a folder under ~/builder, a session that works there, and an entry for Deck. From then on that crew's session does the building, and the steward carries decisions between crews as you add more.

The crew's first job is its bead, a short description of where the project is going. It writes one with the write-bead skill, and every piece of work after that is measured against it.

Advice for the first week

Bring a problem. You do not need a specification. The steward's fastest route to one is a working thing you can react to.

Correct it with the reason attached. "No, do it this way" gets you compliance. "No, because that path drops the error and we lost a day to it" gets you a rule the steward can apply to cases you never mentioned.

Some decisions stay yours. Merging, spending money, publishing anything, changing what a project is for and deleting things are always your call, however much you come to trust the steward. It brings them to you with a recommendation.

Its instructions are yours to edit. The steward's charter is ~/builder/steward/CLAUDE.md. It records what the two of you learn about working together, and it is worth reading every few weeks.

Work on one thing at a time in each crew. Builder shows you everything you have in flight, and a long list is how you notice you have stopped finishing things.

Where to go next

• How Builder works shows how the parts fit together.
• The glossary explains each word Builder uses.