Set up
Set up is the half of crew's page where crew is configured: projects, workspaces, worktrees,
machines and crew's own settings. Every form runs a crew command, so nothing here is out of reach
of the terminal (or of an agent). The other half is Voice OS, where you talk to the
sessions.
The examples use a store: store-front (the web app), store-api, checkout-api and signals.
Use your own repos.
Contents
- Opening it
- The board
- A project
- Checking a project
- Workspaces
- Worktrees
- A new worktree
- Setup with Claude
- Machines
- Settings
- Moving to another machine
- First run
- On a phone
Opening it
crew
Bare crew starts crew's server if it is not running and opens the page in your browser. With no
terminal, over SSH or with --no-open, it prints the link instead. The page opens on Home:

Pick Set up. Each card says what is waiting there ("2 things need you" is the board's problems strip). Enter opens the highlighted one. Ticking Always open Voice OS skips Home when you open the page fresh, once there is a worktree to talk to (the very first time, Home is the first run); the crew mark at the top left always brings you back to it, and Voice OS's settings turn it off.
Set up shows one machine at a time. The bar along the top has the crew mark, the machine picker (This Mac, and any other machines — one with something broken shows it when you open the menu) and the breadcrumbs of where you are. Esc goes up one breadcrumb.
The board
The board is the machine's front page: what it has, and what needs you.

From the top:
- Setup with Claude — a box to ask the machine's Claude anything about setting it up. Open goes to the whole conversation.
- The problems strip — one row per thing that needs you: a worktree whose install or servers failed, or a project whose check failed. Each row has Fix (the page where the failure is shown, with its evidence) and Fix with Claude (the same failure handed to Setup with Claude). Nothing broken, no strip.
- Workspaces and Projects — two tabs over one table, Workspaces first because that is where you work. A line under the tabs says what each one is.
Workspaces lists each workspace with its projects and its worktrees as chips: green when ready, red with what failed, "+N" for the rest, and + new to make another. New workspace opens the form. With no workspace yet, the tab offers the three ways to start instead: New workspace, Import (from another machine's export) and Ask Claude.

Projects lists every project on the machine, one line each: its install, its dev servers with their ports, the workspaces it is in, and its state — Check (never checked), check failed, or ready. A long cell ends in "…" and shows the whole of it on hover; a list says its first entries and how many more ("web :3000 · api :4000 +2", "store-front +1"). A click anywhere on a row opens the project; its own buttons do only their own thing. Add project clones a git URL into crew's own folder; Use a folder on this Mac is there for a repo with no remote, and crew's worktrees then branch from your checkout.
A project with no dev servers (a library, infra) is a whole project: nothing flags it, and its sessions read, change and test its code like any other.
A project
Click a project for its page: what crew recorded, one line per fact — its install and env command, each dev server, each Environment variable, the workspaces it is in, where its code comes from and where it is. A long value ends in "…" with the whole of it on hover.

When its last check failed, the page opens on that: the step it stopped at (checkout, install or servers), the end of the log, and what it means ("its worktrees keep their code, and the project stays as it was set up"). Fix with Claude, Edit setup, Check again and Full log sit under it.
Remove project at the bottom takes it out of crew. It asks first, and says what goes with it: a clone crew made goes to crew's trash, a folder you added is never touched.
Edit setup
Edit setup opens the project's form:

- Install runs in every new worktree. Empty means crew picks the package manager from the
lockfile. The env command runs after it, for env files that come from a vault
(
op inject -i .env.tpl -o .env). - Dev servers — a name, the command, the folder it runs in and a port. The command must listen
on
$PORT: every worktree gets its own port, and the one here is only a reference. A server with no port is a process that doesn't listen (a worker, a watcher). Renaming a server keeps its environment. - Environment — variables crew sets in every worktree of the project, pointing it at the other
projects of the same worktree. Pick the variable, where its value comes from (
store-api's URL, its host, its port, or your own text with those inside it, likews://{{signals.host}}/rtc) and which server gets it. Before you save, each line shows the value it would get in every worktree; one that can't resolve says why. In the terminal,crew add binding <project> --scanproposes thelocalhostlines of the project's.envfiles.
Save records it. Stuck? Ask Claude sends the
form's project to Setup with Claude, which picks up from there. In the terminal, the Environment
is crew add binding.
Checking a project
Check (on the board) or Check again (on the page) proves the project works from nothing: a
clean checkout, the install, then every dev server has to answer. The check page follows it step
by step while it runs. A pass is a green line on the project; a failure stays on the project page
with its evidence until you fix it and check again. It touches nothing you work in — the check has
its own scratch checkout, cleared once it passes. Terminal: crew check project store-api --wait.
Workspaces
A workspace is the projects you work on together. Each worktree gets a copy of every one, wired to each other.
New workspace asks for a name and the projects. Each project is in a worktree of its own (worktree, the default) or direct — its one checkout, shared, for a project you never branch. One that can't be direct (it is already direct in another workspace, or has worktrees) says why when you save. How they connect lists which Environment lines between the ticked projects resolve. Creating it also makes its first worktree, main, with every server tried.
A workspace's page is its worktrees, one card each: its state, its size on disk and its dev servers as chips (red for one that died), with Start and Open in Voice OS. The gear beside the name opens the workspace's settings: its projects, where you add or take one out (every worktree gets the change), and Remove workspace. Taking a project out, or removing the workspace, opens a confirm that says, per checkout, what would go — uncommitted files, commits that are not on the base branch and the space on disk — before anything is removed.
Worktrees
A worktree's page is one working copy of the workspace:

- Its name, with Rename and Duplicate as small icons beside it, and Open in Voice OS on the right.
- Dev servers — one card for everything about its servers. Its top line says what is going on (running, a server that died, verifying, installing, a failed install) and has the buttons that fit: Start, Stop, Restart, Verify, or Install again after a failed install, and Fix with Claude whenever something failed. Under it each server, with its state and, while it runs, its URL. Click one and its log opens beside the list, following its output; a server that died opens its log by itself.
- Verify checks that each server comes up from scratch, and it happens right in the card: each server's line turns green as it answers, and its log is the output of that try. Servers that are running are stopped first (the card asks before it does), and they stay stopped after.
- While a worktree is being made or a project installs again, the card lists its projects instead, each with the step it is on, and a project's line opens what its install is printing. A failed install stays that way, with its output, until Install again or Claude fixes it.
- Environment — one card: the values set for this worktree only, for every project or one of
them (
STRIPE_KEY=sk_test_…). Each says set for this worktree and what it replaces ("instead of store-front's value: store-api api's URL"): it wins over the project's Environment, scoped values included. The form at the bottom of the card sets one, and What each server gets opens to show the final set, server by server. Terminal:crew add override. - On disk — its size and folder, and how each project is in it.
Rename moves its checkouts and renames crew's branches; it is refused while its servers run or setup is busy with it. Duplicate makes fresh checkouts of the same projects on new ports, with the values set for this worktree copied across. Remove worktree shows what would go first, like a workspace; removing a workspace's last worktree removes the workspace too.
A new worktree
+ new on a workspace, or New worktree on its page:

Start from shows each project's base branch and how far it is behind origin. Pull first
fast-forwards the bases before branching (it never touches a branch you have checked out). Each
project gets a crew/store-front/<name>/<project> branch.
Create worktree takes you to the new worktree's page, where its Dev servers card follows crew's runners: each project with the step it is on (checkout, install, servers tried), then its servers as they answer. A project that fails stops there with its output and Fix with Claude; the others keep what they have.
Setup with Claude
Each machine has its own Claude for setting up: a Claude Code session in your home folder with the crew CLI, always on, one conversation.

Ask it anything you would do in the forms, or what you don't know how to do: "add the signals repo to crew and give it a worktree", "why does store-api's install fail?", "check this machine". It reads the repo, works out the install and the dev servers, asks only what it can't know, and records it with crew commands. Each crew command that recorded something gets a ✓ recorded line, taken from the command it ran — not from what Claude says about it.
It is drawn with the same pieces as a session in Voice OS: its steps, the reply as it arrives (with
a caret), a bar while it compacts its context, and the sub-agents it has running. What it waits on
is docked at the foot of the card, right above where you type, as Voice OS docks it above the voice
bar: a question with its options as rows, Something else… for your own answer and ✕ to
decline it; a plan to approve or change; a permission as Allow / Always allow … / Deny (or Deny and
say why…); a /clear or /compact to confirm. Words you send while it works wait in the queue under the ask —
▲ now sends one at once, ✕ cancel drops it — and go in order when the turn ends; Stop
stops the turn. Fix with Claude and Ask Claude anywhere in Set up start here, with the
failure or the form already said.
While Claude works on a worktree, that worktree shows beside the chat: its Dev servers card, live, so you see servers stop, restart and answer as Claude changes things, and their logs a click away. It picks the worktree up from the crew commands Claude runs and the messages you send, and moves when Claude moves to another one; Fix with Claude from a worktree opens it at once. × closes it until the next worktree is named.
Type @ in the box for this machine's worktrees and projects: pick one and its name goes into your message, spelled as crew spells it.
It is not part of voice: what you type goes straight to the setup session, never through Voice OS's kernel; Voice OS never routes your words to it, speaks for it or shows its questions, and no button here has a word to say. On another machine, its chat is that machine's setup session, and its questions are answered the same way.
Machines
The machine picker's Add a machine… sets one up: install crew on that computer or VM (crew server remote there checks it is ready); then give its SSH address (what ssh <host> logs
into with no password) and a Name, and press Connect without Claude, or Connect with
Claude to have Setup with Claude do it. A remote machine has
the whole path.
A machine's page says how it is reached, which crew it runs and what is on it — each project with its state and worktree count. Check with Claude asks that machine's Claude to look at the connection, tools, disk and projects; Rename and Remove machine are there too. Everything else in Set up — the board, the forms, Setup with Claude — works on another machine the same way as on this one: pick it in the picker. A machine that runs an older crew says so in place; crew updates it from here.

Settings

- Update — on This Mac's settings, when a newer crew is out. crew's server keeps running until
you restart it; other machines are updated from here after. A build from source says so:
crew updatereplaces it with the latest release. - This machine — the server IP (how other devices reach it), the SSH host (your ssh config alias for it) and the proxy domain and ports, for named URLs for every server that open on your phone too. Trust on other devices shows how to trust crew's certificate, once per device.
- Disk — Trash is removed checkouts waiting to be deleted (crew empties it in the background; Empty now does it now). Left behind is what crew can clear: old checks, logs of removed worktrees, stale locks. crew sweeps these on its own at most hourly; Clean up runs it now. Both say what they will remove before they do.
- Move to another machine — Export… and Import… (below).
- From before crew 2.0 — only when a workspace still has the old flat layout: Migrate shows what moves, then moves it.
- crew log — the end of crew's debug log on that machine.
- Uninstall — stops every dev server and crew's server, and removes crew. Your config and
worktrees in
~/.crewstay, so a reinstall picks up where you left off; Uninstall and purge… deletes them too. Either wants the word typed first. It ends on a "crew is uninstalled" screen.
Moving to another machine
Export… (Settings) is its own page: tick workspaces and the projects in them come along; projects in no workspace are ticked on their own. A project with no git remote goes as setup only, and the other machine points it at a folder. The page says what goes with the file (projects by remote, their install and env commands, dev servers, bindings, workspace membership) and what stays (worktrees, ports, worktree values, .env files), and Save crew-export.json downloads it.

Import… on the other machine takes the file (drop it, or choose it) and shows crew's plan with every choice up front:

- Needs a choice — a project with no remote: Point at a folder or Skip. A name taken by a different repo here: Import as store-api-2, Replace mine (offered only when no workspace here uses yours) or Skip. A clone folder already taken: point at a folder, import under another name, or skip.
- Will be done — the clones. A repo you already have checked out in your code folders is cloned too: crew keeps its own copy, so its branches never land in yours.
- Workspaces — each is made with its main worktree. One whose project is skipped or renamed can't be made (crew makes a workspace from its members' exported names) and says so.
- Already here — folded; kept as they are, or Replace mine with the export's setup.
Import stays off until every choice is made (Skip counts), then runs everything at once: the
projects, then each workspace, with its install shown the way the first run shows it. A replace
asks first. It ends on Open Voice OS (the first workspace's session) or Go to the board.
Terminal: crew import <file> prints the same plan (found is a checkout you already have), and
crew import <file> project <name> --path=<dir> uses it instead of a clone.
First run
The first time crew's page opens on a machine, Home is the first run: the crew wordmark and three ways in.
- Import opens Import with an export from another machine or a teammate.
- Set it up step by step goes through the three steps below, each on its own screen.
- Skip goes straight to Set up, where an empty board offers the same ways to start, or Setup with Claude does it for you.
The first run shows once. Whichever way you pick, Home is the launcher from then on, even if you later remove every workspace. A machine that already had worktrees when crew got this never sees it.

- Pick your projects. crew lists the git checkouts in your usual code folders (
~/code,~/projects,~/dev,~/src,~/Developer,~/work,~/repos). Tick the ones you work on: each is cloned fresh from its remote into crew's own folder, and yours is never touched (one with no remote is used where it is). Add by URL or Use a folder on this Mac for anything else. - Make a workspace. Name it and tick its projects; the page shows the session it makes
(
<name>/main). - Getting it ready. Its
mainworktree is checked out, its.envcopied and each project installed, one row per project. It moves on by itself; an install that fails stays on screen with its last lines, Fix with Claude, Retry and Continue.

Then Open Voice OS opens that worktree's session, or Go to Set up opens the board. A
project's dev servers, when it has any, go on its Edit setup form, or Setup with Claude works
them out. crew's own state says where the steps start, so projects added with a terminal crew add project are already there, and reopening the page while the worktree installs comes back to its
progress.
On a phone
The page works at phone width: the toolbar, the strip and the forms stack, and the tables scroll sideways.

To reach it from a phone, set the proxy domain in Settings and trust crew's certificate on the phone (Other devices has the details).
More: Tutorial 1 (the same steps, on the page and as commands) · Voice OS · every command