Workbench
Projects And Workspaces
How Alera models a project, a workspace, and a Git worktree, and how the sidebar keeps many of them in view.
On This Page
Three words carry the workbench. Getting them straight makes the rest of Alera obvious.
Project#
A project is a folder you register in Alera: an existing local path, or a clone from a Git URL. Add Project in the sidebar offers both, as Local Folder and Clone From URL. A clone runs in the background and reports its progress, so the rest of the workbench stays usable.
Git is optional. A plain folder is a valid project.
Workspace#
A workspace is your working context inside that project. Registering a project creates its first workspace, which points at the project path itself.
New Workspace adds more. A workspace can share the project folder, or, in a Git-backed project, live in its own linked Git worktree, a separate checkout, so two tasks can change the same repository without sharing a working tree.
Worktree#
A worktree is the Git mechanism behind a linked workspace. When you create one, Alera makes a new local branch from a source branch, or attaches the workspace to a branch you already have.
Non-Git folders are not second-class: they hold several workspaces too, all sharing the folder. Only a Git project can give a workspace its own linked worktree, because without Git there is nothing to link. See Worktrees for the parallel-agent workflow this unlocks.
What Lives In A Workspace#
Once a workspace is open you get:
- Terminal tabs, each a full PTY owned by the runtime host, in splittable panes
- A layout that belongs to that workspace, not to a global window
- A right panel with Explorer, Search, Source Control, and Pull Request tools scoped to that checkout, plus the terminals you open next to the main one (Terminals And Panes)
- Optional setup the first time Alera creates a linked workspace
Closing the desktop window does not tear the terminals down: with Show Tray Icon on, the default, Alera hides to the tray and the sessions keep running. Sessions belong to the runtime host, so when you quit, Alera asks before stopping terminals that still have work, and you can leave the runtime open and reattach later (Sessions Outlive The Window).
Keeping Many Workspaces In View#
The sidebar groups workspaces by project and shows, for each one, whether its agents are working, waiting for you, or done. Right-click a workspace for the rest:
- Pin Workspace keeps it in a Pinned group at the top.
- Manage Tags and Set Section organize long lists; the view options switch the grouping between projects, sections, and a flat list.
- Set Parent Workspace nests related workspaces, so a task and its follow-ups stay together.
- Sleep and Archive take a workspace out of the way without deleting it.
- Hand Off moves the work in progress on the main checkout into a new child workspace, and Hand On brings a child’s work back onto the main checkout.
Typical Loop#
- Register the project (local folder or clone).
- Work on the project folder for the default branch, or create a workspace per task.
- Launch agents in that workspace’s terminals.
- Review the diff and open a pull request from the same workspace when the task is done.
If you are about to run two agents on the same files, create a second workspace in its own worktree first. Sharing one checkout is how parallel agents turn into stash fights.