Getting set up: a workspace, its projects, a worktree

This takes you from an empty crew to two copies of your stack running side by side, typed out as commands. The quickest way is the browser instead: crew opens crew's page, where Set up has a form for each step and a Claude that runs them for you. The example is a store with an API and a web app; use your own repos.

1. Install

curl -fsSL https://raw.githubusercontent.com/FurlanLuka/crew/main/install.sh | sh

crew needs git and tmux: crew doctor says whether they are there, and crew doctor --install installs them (the first crew command that needs them offers it). For agents in the worktrees you'll want Claude Code, though any agent with a shell can drive crew.

2. Add your projects

A project is a repo crew knows about. Give it a URL and crew clones it; give it --path and crew adopts a checkout you already have.

crew add project store-api git@github.com:example/store-api.git
crew add project store-app --path=~/code/store-app

Tell crew how each one runs. The dev command must listen on $PORT — crew hands every copy its own port, so next dev -p $PORT, uvicorn --port $PORT or process.env.PORT:

crew dev add store-api --name=store-api --port=3000 --cmd="npm run dev"
crew dev add store-app --name=store-app --port=3001 --cmd="npm run dev"

The installs are detected from the lockfile (and mise). If a checkout needs more, add --setup="make sync"; if its env files come from a vault, --env-cmd="make get-env".

3. Point the services at each other

The web app needs the API's URL, and that URL is different in every copy. A binding says so once:

crew add binding store-app --scan            # what store-app's .env seems to point at
crew add binding store-app --scan --apply    # add the clear ones
crew add binding store-app --var=API_URL --url=store-api   # or say it yourself

At start, API_URL becomes http://localhost:<the port store-api got in that copy>.

4. Prove a project works from nothing

Before building on it, check that a fresh checkout installs and its servers come up:

crew check project store-api --wait

A failure keeps the checkout with its evidence; crew fix check/store-api opens Claude on it.

5. Make the workspace

A workspace is the set of projects a piece of work touches. Creating it also makes its first copy, main:

crew add workspace store-front store-api store-app
crew setup status store-front/main --wait    # one runner per project: checkout, install, smoke

Each project gets its own git worktree on a crew/store-front/main/<project> branch, its .env copied in, its install, and a smoke start of its servers. A failure is recorded with its evidence; crew fix store-front/main hands it to Claude.

6. Run it

crew dev start store-front/main           # servers up on this copy's ports
crew dev check store-front/main --wait    # did each one start listening?
crew claude store-front/main              # Claude, told where it is and how to reach everything

The Claude inside knows its worktree and has crew dev logs, crew dev check, crew run (tests and scripts with the same URLs the servers got) and crew fix at hand.

7. A second copy

crew add worktree store-front/wrk1 --pull   # fresh base branches, then a copy of everything
crew dev start store-front/wrk1             # different ports; nothing collides

Now two features can move at once, each with its own branches, servers and agent. Add a project to an existing workspace later with crew add workspace store-front checkout-api.

Or do it all in the browser

crew opens crew's page; Set up is every step above as a form — it starts from the repos already on your machine (crew add project --scan is the same list), shows the command each form runs, previews a binding's value in every worktree before you save it, and says what a removal would cost before it removes anything. Each machine has a Setup with Claude chat there too: "make a worktree in store front for the search fix". The Set up guide walks every page. In the terminal, crew launch picks a worktree and opens Claude or your editor on it.

Let Claude Code drive it

Any agent with a shell can run these commands. Claude Code also gets a plugin with the full command reference, a crew agent and guided skills for setup, import, status and the proxy:

/plugin marketplace add FurlanLuka/crew
/plugin install crew@crew

Then ask in plain words: "set up crew for store-api and store-app", "what's running?". The plugin lists what it ships.

Staying current

crew update

It installs the latest release of crew, and of Voice OS once you have it; a running server keeps the old version until crew server restart. crew update --check only asks; crew also mentions a newer release when one is out.

More: Set up in the browser · how crew works · every command · running crew on a remote VM