Reference
Project setup
Setup and teardown commands, files carried into each worktree, and what Run starts — the per-project settings behind fresh worktrees and the Run button.
A brand-new git worktree is a clean checkout: no node_modules, no .env, nothing that isn’t committed. These settings are how you tell Raven what a usable copy of your project needs, and what the Run button should start. Find them under Settings ›
The first three apply to worktree workspaces, which are the ones that get a fresh checkout. Local workspaces run in the folder you already set up.
Setup command
A shell command run in a new worktree after it’s created, before the agent starts. Almost always a dependency install.
Raven suggests one from the lockfile it finds, as the field’s placeholder:
| Lockfile | Suggested command |
|---|---|
pnpm-lock.yaml |
pnpm install |
yarn.lock |
yarn install |
bun.lockb |
bun install |
package-lock.json |
npm install |
That’s the whole of the detection — a lockfile is unambiguous evidence — and it stays a suggestion until you save it (with no lockfile, the placeholder is only an example). Raven won’t infer a build step or run a script it guessed at. Enter whatever your project actually needs, chain steps with &&, or leave it empty if there’s nothing to do.
If setup fails, the workspace says which step failed and why, and offers to re-run it or edit the command. It doesn’t start the agent on a half-provisioned checkout.
Files carried into each worktree
Files copied into every new worktree. These are the gitignored ones a fresh checkout can’t have but your app needs to run — .env and friends.
Raven prefills this list with gitignored .env* files at your repo root. Add or remove paths as needed.
Two things follow from these being Raven-managed rather than yours:
- They’re copied from your main checkout each time, so a worktree always gets your current values.
- They’re excluded from the work-in-progress capture on archive, so secrets never end up in the git object store and a reopened workspace gets fresh copies rather than stale ones.
Teardown command
A command run in the worktree just before it’s removed, on archive or delete. Use it for anything that outlives the folder — stopping a container, freeing a port, dropping a scratch database. It’s best-effort and capped at a minute; leave it empty if there’s nothing to undo.
Run button
What the Run button in the workspace header starts — every workspace has the button, local or worktree, and ⌘R presses it. A picker on the row chooses between two things:
- Terminal command — a shell command, run from the workspace’s folder in the workspace’s own run terminal on the Terminal surface, which comes to the front. Pressing Run again stops that terminal’s shell and starts the command fresh.
- Simulator — Run opens the Simulator surface, boots the workspace’s device and runs the simulator run command below, exactly as the pane’s own Run does. No terminal opens; a failed build shows in the pane. Your terminal command is kept while this is picked.
Until a project has a Run, the button reads Set up Run… and opens a menu with two ways to get one: Ask an agent to set up Run and Set up Run. Once it does, the chevron’s menu opens with what Run starts now — Runs this command or Opens the Simulator — then the same two actions under their new names:
- Ask an agent to change what Run starts — starts a chat that works it out from the project and saves it, filling in the setup command too if that’s still empty.
- Change what Run starts — jumps to this row.
Simulator run command
The build-and-launch command behind Launch and Run on the Simulator surface. Nothing runs until one is saved: the surface’s Run settings page suggests the Xcode project Raven finds and saves the command when you accept it, or takes a command of your own (React Native, Flutter, a build script). The workspace’s device is passed as $RAVEN_SIMULATOR_UDID; which iPhone that is gets picked from the pane’s header.
Home branch
Each project has a home branch — the default starting point for new worktree branches and the target for pull requests. Raven initially selects the remote’s default branch. Change it under Settings ›
When creating a worktree workspace, the from picker lets you start that one workspace from a different branch, local or remote. This changes its starting point; its diffs and pull requests still target the project’s home branch. A local workspace gets an on picker instead: the branch it checks out in your project folder when it starts. Either kind can switch branches later from the composer’s branch readout.