02 - Workspace#
A workspace is the central unit of work in Helmor. It represents an isolated working copy — a branch, a file tree, and a set of sessions — dedicated to a single task.
What a workspace provides#
- Branch isolation — each workspace gets its own Git branch so agent edits never contaminate other work.
- File tree — browse, search, and edit files scoped to this workspace's state.
- Session history — every agent conversation and its resulting changes are recorded.
- Diff baseline — changes are compared against the workspace's target branch.
Isolation modes#
| Mode | How it works |
|---|---|
| Worktree (default) | Creates a dedicated git worktree directory. Full isolation — the workspace has its own branch and disk copy. |
| Local | Points directly at the repository root. Multiple conversations share the same files. Useful for quick edits without branching overhead. |
| Chat | A scratch directory with no Git binding. Good for exploratory questions where you don't need file changes. |
Lifecycle#
Workspaces move through four states:
- Initializing — database record created; filesystem setup in progress.
- SetupPending — a project setup script was detected (e.g., dependency install). Run it or skip.
- Ready — the workspace is usable. Start sessions, browse files, review diffs.
- Archived — task complete. The worktree is cleaned up and the branch deleted (if Helmor created it).
Branching behavior#
- FromBranch — Helmor forks a new branch from your selection. The workspace owns the branch; archiving deletes it.
- UseBranch — the workspace attaches to an existing branch. The branch is preserved on archive.
Best practices#
- One task per workspace keeps review scoped and diffs small.
- Archive completed workspaces to keep the sidebar clean.
- Use worktree mode for any task that modifies files — local mode risks cross-contamination if multiple workspaces touch the same code.
Related#
- Create a Workspace — step-by-step creation guide.
- Session — what happens inside a workspace.