04 - Create a Workspace#
A workspace is an isolated working copy where one task lives. It gives your agent a clean environment tied to a branch, separate from everything else in the repository.
Create a workspace#
- Select a repository from the sidebar.
- Click New Workspace (or press the
+button). - Choose a base branch to fork from (e.g.,
main). - Helmor creates a dedicated Git worktree and auto-names a new branch for the task.
The workspace appears in the sidebar within milliseconds — Helmor writes the database record instantly while the filesystem setup finishes in the background.
Isolation modes#
| Mode | Description | Use case |
|---|---|---|
| Worktree (default) | Dedicated git worktree directory with its own branch. | Standard agent tasks — full isolation. |
| Local | Operates directly on the repository root. | Quick edits where you don't need branch isolation. |
| Chat | Scratch directory with no Git binding. | Exploratory questions, no file changes needed. |
Workspace lifecycle#
Initializing → SetupPending (optional) → Ready → Archived
- Initializing — database record created, disk setup in progress.
- SetupPending — a setup script was detected and needs to run.
- Ready — workspace is usable; start a session.
- Archived — task complete. In worktree mode, the branch is deleted on archive since the workspace owned it.
Best practices#
- One task per workspace. Keep scope tight for clean diffs and easy review.
- Name tasks clearly — the workspace title becomes your mental index.
- Archive when done — frees the worktree and keeps the sidebar focused.
Next: Send Your First Agent Task to start working.