# Workspace Management (/docs/verdent/common-workflows/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.

<Note>
  Each workspace can contain multiple tasks. Tasks share the workspace's file state but have their own conversation context and agent.
</Note>

***

## When Workspaces are Ideal [#when-workspaces-are-ideal]

Workspaces solve common parallel development challenges:

<Tabs>
  <Tab title="Frequent Interruptions">
    **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.

    <Steps>
      <Step title="Focus on your current task">
        Work inside one Workspace and push forward
      </Step>

      <Step title="A new task appears">
        Urgent bug or request that needs immediate attention
      </Step>

      <Step title="Create a new Workspace">
        Work on the new task without interrupting the original
      </Step>

      <Step title="Run multiple tasks in parallel">
        Each task progresses in its own Workspace
      </Step>

      <Step title="Switch freely at any time">
        Jump between Workspaces without mental reset
      </Step>

      <Step title="Integrate results when done">
        Merge back to the main codebase or submit directly
      </Step>

      <Step title="Resume original work">
        Pick up exactly where you left off
      </Step>
    </Steps>
  </Tab>

  <Tab title="Uncertain Solutions">
    **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.

    <Steps>
      <Step title="Create Workspaces for each solution">
        All solutions are isolated from each other
      </Step>

      <Step title="Run them in parallel">
        Implement and validate simultaneously without interference
      </Step>

      <Step title="Switch freely and compare results">
        Compare complexity, code changes, and real execution behavior
      </Step>

      <Step title="Keep the best, discard the rest">
        Merge the optimal solution, drop the others
      </Step>
    </Steps>
  </Tab>

  <Tab title="Complex Requirements">
    **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.

    <Steps>
      <Step title="Break down the requirement">
        Split into independently executable parts with clear boundaries
      </Step>

      <Step title="One Workspace per part">
        Code changes don't interfere between subtasks
      </Step>

      <Step title="Run in parallel, no waiting">
        Modules progress simultaneously
      </Step>

      <Step title="Each part stabilizes independently">
        Test and validate on its own timeline
      </Step>

      <Step title="Resolve merge conflicts">
        Verdent helps with diagnosis and resolution
      </Step>

      <Step title="Merge incrementally, deliver holistically">
        Assemble the final result module by module
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## What You'll Learn [#what-youll-learn]

* Create and name workspaces
* Switch between workspaces
* Rebase changes to the main branch
* Clean up completed workspaces

***

## Understanding 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 [#creating-workspaces]

### Quick Create [#quick-create]

Press `Cmd+Shift+N` (macOS) or `Ctrl+Shift+N` (Windows)

### Step-by-Step [#step-by-step]

<Steps>
  <Step title="Click New Workspace">
    Click **New Workspace** in the Top Bar
  </Step>

  <Step title="Name Your Workspace">
    Enter a descriptive name (e.g., `feature-auth`, `bugfix-123`)
  </Step>

  <Step title="Start Working">
    You're now in the isolated workspace with its own branch
  </Step>
</Steps>

### Naming Conventions [#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 [#managing-workspaces]

### Viewing All Workspaces [#viewing-all-workspaces]

Click **All Workspaces** in the Top Bar to see all active workspaces.

### Workspace Hierarchy [#workspace-hierarchy]

```mermaid
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 [#switching-workspaces]

| Action                 | Shortcut                 |
| ---------------------- | ------------------------ |
| **Next Workspace**     | `Ctrl+Tab`               |
| **Previous Workspace** | `Ctrl+Shift+Tab`         |
| **Select Specific**    | Click **All Workspaces** |

***

## Workspace Actions [#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 [#sync-from-main-workflow]

Keep your workspace up to date with the main branch:

<Steps>
  <Step title="Sync">
    Click **Workspace Actions → Sync from Main**
  </Step>

  <Step title="Resolve Conflicts">
    If conflicts appear, resolve them in the affected files
  </Step>

  <Step title="Continue Working">
    Your workspace now has the latest changes from main
  </Step>
</Steps>

### Rebase Workflow [#rebase-workflow]

When your work is complete, rebase changes to the main branch:

<Steps>
  <Step title="Commit Changes">
    Use Source Control (`Ctrl+Shift+G`) to stage and commit with a descriptive message
  </Step>

  <Step title="Test">
    Run tests to ensure everything works
  </Step>

  <Step title="Rebase">
    Click **Workspace Actions → Rebase to Main**
  </Step>

  <Step title="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**.
  </Step>
</Steps>

### Pull Request Workflow [#pull-request-workflow]

Create a pull request from your workspace:

<Steps>
  <Step title="Commit Changes">
    Use Source Control (`Ctrl+Shift+G`) to stage and commit with a descriptive message
  </Step>

  <Step title="Create PR">
    Click **Workspace Actions → Create PR**
  </Step>

  <Step title="Review">
    The PR is created from your workspace branch to the main branch
  </Step>
</Steps>

***

## Cleaning Up Workspaces [#cleaning-up-workspaces]

### When to Delete [#when-to-delete]

| Scenario            | Action           |
| ------------------- | ---------------- |
| Work rebased        | Delete workspace |
| Experiment failed   | Delete workspace |
| Approach superseded | Delete workspace |
| Still active        | Keep workspace   |

### How to Delete [#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.

<Warning>
  Uncommitted changes are lost when deleting a workspace. Always commit work before deleting.
</Warning>

***

## Session Controls [#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 [#faqs]

<Accordion title="Can I rename a workspace?">
  Not directly. Create a new workspace with the desired name, rebase changes, then delete the old workspace.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="What happens if I delete the project folder?">
  All workspaces are inside the project folder. Deleting the project folder deletes all workspaces.
</Accordion>

***

## See Also [#see-also]

<CardGroup cols="2">
  <Card title="Workspace Isolation" icon="shield-halved" href="/docs/verdent/core-features/workspace-isolation">
    How isolation works
  </Card>

  <Card title="Parallel Development" icon="code-branch" href="/docs/verdent/common-workflows/parallel-development">
    Parallel workflow patterns
  </Card>
</CardGroup>