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.
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
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:Rebase Workflow
When your work is complete, rebase changes to the main branch:Pull Request Workflow
Create a pull request from your workspace: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.