Prerequisites

This step is a one-off. Anything already on your machine, you can skip past.

What you install here splits into two groups. First the pieces every track needs in common (Node, git, a package manager, Claude Code). The track-specific test tools — Playwright browsers for web and desktop, Maestro for mobile — come after you pick a track in Choose your target. So on this page, finish the common group and leave the rest for later.

Things that differ by operating system

Item	macOS	Windows	Linux
Which terminal you use	Terminal.app or iTerm2	I recommend Ubuntu on WSL2. PowerShell is technically possible, but the instructions get longer.	Whatever shell ships with your distribution
Verified status	Verified	Install WSL2 first, then run every command inside it	Verified

If you are on Windows, finish the WSL2 install guide before coming back here. Every command in this manual assumes you are inside the Ubuntu shell on WSL2. The mobile track is the exception, though. The iOS simulator runs only on macOS, and the Android emulator is awkward inside WSL2. If you plan to use the mobile track, a macOS or a native Linux machine is the better bet.

1) Node.js 20 or newer

On macOS and Linux: nvm is the easy route

Open a terminal and run these one line at a time.

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Either open a new terminal, or paste these two lines to load nvm right now
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Install Node 20 and switch to it
nvm install 20
nvm use 20

Verify

node --version    # should print v20.x.x
npm --version     # should print something like 10.x.x

If either command prints nothing at all, jump to the “Node will not install” entry in Troubleshooting.

If node --version is missing again in a fresh terminal, the two-line nvm loader did not make it into your shell startup file. It is ~/.zshrc for zsh, ~/.bashrc for bash. Open that file and check that the export NVM_DIR=... lines from the end of the nvm install printout are there. If not, paste them in by hand and open a new terminal.

2) git

macOS

xcode-select --install

This command does not install git on its own — it brings down Apple’s Command Line Tools bundle. A small dialog window pops up to take your consent, and the install starts. If git is already there, it prints a short notice and exits.

Linux and WSL2

sudo apt update && sudo apt install -y git

Verify

git --version    # git version 2.x.x

If this is your first time, register your details once.

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

3) Package manager — pnpm recommended

This base runs under any package manager, but pnpm is the recommendation. One line installs it.

npm install -g pnpm

Verify

pnpm --version    # something like 8.x or 9.x means it is in

Which manager you use gets asked once in /2-setup-base during the first run and pinned into .claude/state/package-manager.json. From then on, the manager you chose is used automatically.

4) Claude Code

The official install guide lives at docs.claude.com/en/docs/claude-code/quickstart. After install, run claude once to log in or register an API key.

claude --version

If a version number prints, you are set. The OpenAI Codex CLI also works in place of Claude Code — in that case, the entry point is AGENTS.md at the repo root, and the same flow applies. If this is your first time, Claude Code is the gentler path.

5) Track-specific test tools — after you pick a track

From here on, what you install depends on which track your app falls under. That decision happens in Choose your target. For now, just preview which tool you will end up installing.

For the web or desktop (Electron) track, the Playwright browsers. After you install dependencies, one line pulls them down.

pnpm exec playwright install --with-deps chromium

This command downloads the actual browser the tests will launch. The first time it is a large download and takes a few minutes. The base’s init.sh also runs this line on its own when it sees @playwright/test in the dependencies.

For the mobile track, the Maestro CLI.

curl -Ls "https://get.maestro.mobile.dev" | bash

After install, maestro --version should print in a fresh terminal. Fuller instructions live at docs.maestro.dev.

If you have not picked a track yet, skip number 5 and move on. After you choose a track, the base tells you which tool it needs.

6) The test environment file

The base ships a file called .env.test.example. It lists only the names of the environment variables the tests need — the actual values are blank. Copy it to make a file you will fill with your own values.

cp .env.test.example .env.test.local

.env.test.local is in .gitignore, so it never goes up to git. Real values like a test account password belong only in this file.

Where real keys go

Values like a test account password or an API key must never be hardcoded into a source file or committed to git. They belong only in .env.test.local. And the account you use here has to be a dedicated test account. Do not test with the admin account or a real user account you actually rely on.

Next

Once the common group (Node, git, package manager, Claude Code) is in place, head to Clone and install. The track-specific tools come afterward, while you are choosing a track.