Workspaces & worktrees
A workspace is one task. Each one is backed by its own git worktree on its own branch — the isolation that lets many agents run in parallel without collisions.
Creating a workspace#
Press ⌘⇧N, click the + next to a project, or start one from a GitHub issue. You give it a name, a base branch, and an optional task prompt for the agent.
New Workspace in 2xlabs
On create, NeuralCode runs:
git worktree add -b <prefix>/<slug> <worktree_path> <base_branch>
…giving the workspace a fresh checkout and branch. If you wrote a task prompt, it's seeded into the chat ready to send.
Branch naming#
The branch is <prefix>/<slug>, where the slug is your workspace name lowercased and hyphenated. Two strategies are available in Settings → Git:
| Strategy | Example branch |
|---|---|
| Simple (default) | code-agents/fix-login-redirect |
| Conventional | Pick a type per workspace — feat/…, fix/…, chore/…, docs/…, refactor/… |
If a branch name already exists, a short unique suffix is appended so the worktree always succeeds.
Workspace statuses#
Every workspace shows a status indicator in the sidebar and header. The running state animates as a braille spinner; the rest are colored dots.
| Indicator | Status | Meaning |
|---|---|---|
| Idle | Created, but no agent run is active yet. | |
| ⠋ | Running | An agent run is actively streaming. |
| Ready to review | The run finished successfully — inspect the diff. | |
| Error | The last run failed. | |
| Merged | The branch has been merged into its base. | |
| Archived | Removed from active lists; shown under History. |
Merge, archive & delete#
Merge
Merging commits any pending changes in the worktree, then runs a git merge --no-ff of the workspace branch into its base branch in the original repo. The workspace is marked Merged (the worktree and branch are left in place so you can keep iterating).
Archive
Archiving stops any running agent and terminal, then removes the git worktree and branch. The workspace record is kept and moves to the History section of the sidebar. Merged work stays safely in the base branch.
Running in parallel#
Because every workspace is a separate worktree, you can have a fix, a feature, and a refactor all running at the same time. The sidebar shows each one's live status, and switching between them is instant — their chat, diff, terminal and review state are all preserved.