Automate New Worktree Setup With alera.toml

Update, September 2026:

• On the desktop and the phone, setup now runs in a terminal named Setup, where a failing command does not stop the ones after it. From the CLI, alera workspace add and alera workspace start with --worktree still run setup inline and stop at the first non-zero exit.
• Alera keeps the new workspace for you to open from the sidebar, and a failed copy or setup step leaves the Setup terminal open with its output. A setup warning appears only for an invalid alera.toml or .worktreeinclude, or when the CLI runs setup inline.
• A .worktreeinclude file at the project root copies the gitignored files it lists, with .gitignore-style patterns including globs, even without an alera.toml and alongside a Settings override. The copy list itself still takes literal paths.
• Setup runs only for new worktree workspaces created on this machine. Workspaces that share the project folder never run it, and creating a workspace on a remote SSH host does not run copy rules or setup commands yet.

You know the ritual. You create a fresh worktree for an agent, and before it can do anything useful you are copying .env from the main checkout, remembering which config files are gitignored but required, running install, running bootstrap. Ninety seconds of chores, every single time, multiplied by every agent you want in parallel.

We got tired of performing that ritual by hand, so we taught Alera to perform it for us. The instructions live in a file you own: alera.toml, at the project root.

What It Looks Like#

[worktree]
copy = [
  { from = ".env", to = ".env", overwrite = false },
  { from = ".claude/settings.local.json" }
]
setup = [
  "pnpm install",
  "make bootstrap"
]

Two ideas, nothing more:

• copy brings files or directories from the main project checkout into the new linked workspace. to defaults to from, and overwrite defaults to false so an existing file never gets clobbered silently.
• setup runs commands sequentially from the new workspace root and stops at the first non-zero exit, because continuing a bootstrap after a failure is how you get mysteriously broken environments.

Paths are repo-relative literals. Absolute paths and .. escapes are rejected outright. Globs and custom command environments did not make v1; we would rather ship a small feature that is easy to reason about than a clever one that surprises you.

When It Runs (And When It Does Not)#

Setup applies only to new linked workspaces that Alera creates. It does not run for the main workspace, for workspaces discovered during reconcile, or on removal. That scoping is deliberate: automation should fire at the one moment you asked for something new, not retroactively on things that already exist.

Failure handling follows the same philosophy. If a copy or setup step fails after the Git worktree already exists, Alera keeps and opens the workspace and shows you a setup warning. A half-configured worktree you can see and fix beats a silent rollback you never hear about.

Precedence: Your UI Choice Wins#

Per-project settings in Settings → Projects are the source of truth when present. Choosing Use Repo File clears that override and falls back to alera.toml. When neither exists, there is simply no setup, and nothing happens. No hidden defaults.

One File, One More Job#

The same file can also declare how Pull Requests should talk to your forge:

git_hosting_provider = "github" # or "gitlab" / "azureDevops"

Without it, Alera auto-detects GitHub.com, GitLab.com, and Azure DevOps from origin. Set it explicitly for self-hosted instances. Authentication stays where it belongs, with gh, glab, or az.

The same file can pre-select the Source Branch picker for new worktrees:

[new_workspace]
source_branch = "develop"

When that branch exists (or its origin/ twin does), New Workspace opens on it instead of main. Settings → Projects can set the same default as a UI override.

Combined with worktree-native parallel agents, this turns “new branch for this agent” from a checklist into a non-event. Write the ritual once, then forget it exists.