Workbench
Worktrees
Run CLI agents in parallel by giving each task its own Git worktree, locally or on a remote SSH host.
On This Page
Parallelism in Alera is not “open more tabs.” Two agents sharing one working tree last about ten minutes before they trample each other. The isolation primitive is a Git worktree.
One Worktree Per Task#
When you create a workspace as a New Worktree on a Git-backed project, Alera creates a real Git worktree:
- a new local branch from a source branch, or
- an existing local branch you already have
Each agent then sees only its own checkout. Diffs stay scoped. You can jump between contexts without stashing or remembering what was half-done.
Why This Changes How You Delegate#
When handing a task to an agent costs one worktree instead of a negotiation with your current branch, smaller tasks get easier to start. The tooling nudges you toward the workflow that actually works with several CLIs at once.
From Repo To Running Agents#
- Register a Git-backed project (local folder or clone).
- Open New Workspace, choose New Worktree, and pick the source branch. From Prompt also names the branch and starts your agent profile for you.
- Launch Claude Code, Codex, Amp, fx, or any other CLI in that workspace’s terminals.
The remaining chore used to be setup: every new worktree needs its .env, its gitignored config, its install. That ritual now lives in alera.toml. When the work is done, pull requests and CI checks stay scoped to the same worktree, so what you review is what the agent produced.
Moving Work Between Checkouts#
Sometimes the work starts on the main checkout before you know it deserves its own branch. Hand Off (in the workspace menu, or alera workspace hand-off) moves the work in progress into a new child workspace, and Hand On (alera workspace hand-on) brings a child’s work back onto the main checkout and removes the child, keeping its branch. Live shells follow the move, and running agents are told where the work went.
Worktrees On A Remote Host#
A workspace can also live on another machine you reach over SSH. Add the machine with Add Host under Settings → Remote Hosts, which installs the Alera runtime there, then pick that host in New Workspace, or run alera workspace add --project-id <project-id> --host-id <host-id> --worktree --branch <branch> from the CLI once the project is on that host. The Alera runtime on the host creates the worktree from the repository already there, and terminals, files, search, and source control for that workspace run there. Worktrees created on a remote host do not run setup yet. See Remote Hosts for adding a machine and a project to it.
Installing the runtime does not create a worktree by itself. Authentication uses your SSH agent, ~/.ssh/config, or an identity file you set for the host.
What Is Not A Worktree#
Workspaces on the project folder point at the project path itself; use them for the default checkout. Linked workspaces are the extra checkouts.
Non-Git projects cannot create linked workspaces. They still get terminals, agents, and persistence; they just share one tree.