Each workspace can contain multiple tasks. Tasks share the workspace’s file state but have their own conversation context and agent.
When Workspaces are Ideal
Workspaces solve common parallel development challenges:- Frequent Interruptions
- Uncertain Solutions
- Complex Requirements
Problem: While working on a feature, you’re interrupted by urgent bugs or requests. Your flow breaks, and every return requires a mental “cold start.”Solution: Stay in flow even when new tasks interrupt. Handle new tasks instantly, keep your original work intact, and pick up exactly where you left off.
1
Focus on your current task
Work inside one Workspace and push forward
2
A new task appears
Urgent bug or request that needs immediate attention
3
Create a new Workspace
Work on the new task without interrupting the original
4
Run multiple tasks in parallel
Each task progresses in its own Workspace
5
Switch freely at any time
Jump between Workspaces without mental reset
6
Integrate results when done
Merge back to the main codebase or submit directly
7
Resume original work
Pick up exactly where you left off
What You’ll Learn
- Create and name workspaces
- Switch between workspaces
- Rebase changes to the main branch
- Clean up completed workspaces
Understanding Workspaces
Each workspace is an isolated environment for development:| Workspace Type | Description |
|---|---|
| Base | The main project directory (default) |
| Worktree | Isolated git worktree with independent branch |
.worktrees/{name}. Each worktree:
- Has its own branch checkout
- Can make independent file changes
- Allows staging and committing separately
- Prevents conflicts between parallel tasks
Creating Workspaces
Quick Create
PressCmd+Shift+N (macOS) or Ctrl+Shift+N (Windows)
Step-by-Step
1
Click New Workspace
Click New Workspace in the Top Bar
2
Name Your Workspace
Enter a descriptive name (e.g.,
feature-auth, bugfix-123)3
Start Working
You’re now in the isolated workspace with its own branch
Naming Conventions
| Pattern | Example | Use For |
|---|---|---|
feature-{name} | feature-auth | New features |
bugfix-{id} | bugfix-123 | Bug fixes |
hotfix-{name} | hotfix-security | Urgent fixes |
experiment-{name} | experiment-caching | Experiments |
Managing Workspaces
Viewing All Workspaces
Click All Workspaces in the Top Bar to see all active workspaces.Workspace Hierarchy
Switching Workspaces
| Action | Shortcut |
|---|---|
| Next Workspace | Ctrl+Tab |
| Previous Workspace | Ctrl+Shift+Tab |
| Select Specific | Click All Workspaces |
Workspace Actions
Use Workspace Actions in the top bar for version control operations:| Action | Description |
|---|---|
| Sync from Main | Pull latest changes from main branch into workspace |
| Rebase to Main | Apply workspace changes to main branch |
| Create PR | Create a pull request from the current workspace branch |
Sync from Main Workflow
Keep your workspace up to date with the main branch:1
Sync
Click Workspace Actions → Sync from Main
2
Resolve Conflicts
If conflicts appear, resolve them in the affected files
3
Continue Working
Your workspace now has the latest changes from main
Rebase Workflow
When your work is complete, rebase changes to the main branch:1
Commit Changes
Use Source Control (
Ctrl+Shift+G) to stage and commit with a descriptive message2
Test
Run tests to ensure everything works
3
Rebase
Click Workspace Actions → Rebase to Main
4
Clean Up
To delete a workspace, click the trash icon near the workspace name in the Workspace Bar, or right-click the workspace in the top bar and select Delete.
Pull Request Workflow
Create a pull request from your workspace:1
Commit Changes
Use Source Control (
Ctrl+Shift+G) to stage and commit with a descriptive message2
Create PR
Click Workspace Actions → Create PR
3
Review
The PR is created from your workspace branch to the main branch
Cleaning Up Workspaces
When to Delete
| Scenario | Action |
|---|---|
| Work rebased | Delete workspace |
| Experiment failed | Delete workspace |
| Approach superseded | Delete workspace |
| Still active | Keep workspace |
How to Delete
You can delete a workspace in two ways:- Click the trash icon near the workspace name in the Workspace Bar
- Hover over the workspace in the top bar and right-click to open the menu, then select Delete
Session Controls
Each workspace can contain multiple sessions. Control sessions using these actions:| Action | Description |
|---|---|
| Stop | Terminate the session immediately |
| Delete | Remove session and clean up resources |
FAQs
Can I rename a workspace?
Can I rename a workspace?
Not directly. Create a new workspace with the desired name, rebase changes, then delete the old workspace.
How much disk space does each workspace use?
How much disk space does each workspace use?
Each workspace duplicates working files. If your project is 500MB, each workspace adds roughly 500MB. The
.git directory is shared.What happens if I delete the project folder?
What happens if I delete the project folder?
All workspaces are inside the project folder. Deleting the project folder deletes all workspaces.