Workspace Management
Creating, managing, and rebasing workspaces
Workspaces provide isolated environments for parallel development. Each workspace operates on its own branch, with changes rebased to the main branch when complete.
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:
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.
Focus on your current task
Work inside one Workspace and push forward
A new task appears
Urgent bug or request that needs immediate attention
Create a new Workspace
Work on the new task without interrupting the original
Run multiple tasks in parallel
Each task progresses in its own Workspace
Switch freely at any time
Jump between Workspaces without mental reset
Integrate results when done
Merge back to the main codebase or submit directly
Resume original work
Pick up exactly where you left off
Problem: You face a complex problem with multiple possible approaches. Each seems reasonable, but implementation costs make it hard to know which is truly better.
Solution: Don't argue, run it and see. Instead of debating which solution is right, you run them and let results decide.
Create Workspaces for each solution
All solutions are isolated from each other
Run them in parallel
Implement and validate simultaneously without interference
Switch freely and compare results
Compare complexity, code changes, and real execution behavior
Keep the best, discard the rest
Merge the optimal solution, drop the others
Problem: You have a complex requirement with many interconnected parts (API, business logic, frontend, tests). Sequential workflows cause bottlenecks: one part waits on another.
Solution: Turn step-by-step work into parallel execution. Faster delivery comes from parallelism, not pressure.
Break down the requirement
Split into independently executable parts with clear boundaries
One Workspace per part
Code changes don't interfere between subtasks
Run in parallel, no waiting
Modules progress simultaneously
Each part stabilizes independently
Test and validate on its own timeline
Resolve merge conflicts
Verdent helps with diagnosis and resolution
Merge incrementally, deliver holistically
Assemble the final result module by module
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 |
Worktree workspaces use git worktrees to create completely isolated working copies in .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
Press Cmd+Shift+N (macOS) or Ctrl+Shift+N (Windows)
Step-by-Step
Click New Workspace
Click New Workspace in the Top Bar
Name Your Workspace
Enter a descriptive name (e.g., feature-auth, bugfix-123)
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
flowchart TD
P[Project] --> B[Base - master branch]
P --> W1[Workspace: feature-auth]
P --> W2[Workspace: bugfix-123]
P --> W3[Workspace: experiment-cache]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:
Sync
Click Workspace Actions → Sync from Main
Resolve Conflicts
If conflicts appear, resolve them in the affected files
Continue Working
Your workspace now has the latest changes from main
Rebase Workflow
When your work is complete, rebase changes to the main branch:
Commit Changes
Use Source Control (Ctrl+Shift+G) to stage and commit with a descriptive message
Test
Run tests to ensure everything works
Rebase
Click Workspace Actions → Rebase to Main
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:
Commit Changes
Use Source Control (Ctrl+Shift+G) to stage and commit with a descriptive message
Create PR
Click Workspace Actions → Create PR
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
An Archive option is also available in the right-click menu if you want to keep the workspace for later reference.
Uncommitted changes are lost when deleting a workspace. Always commit work before deleting.
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?
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?
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?
All workspaces are inside the project folder. Deleting the project folder deletes all workspaces.