---
title: "Creating Workspaces"
description: "Learn how to create and configure workspaces for your development tasks"
---

<Frame>
<img style={{maxHeight: "400px"}} src="/images/workspaces-create-new.png" alt="Create workspace view showing project selection, repository list, and task input" />
</Frame>

A workspace is your task execution environment where you work with coding agents. Each workspace can include one or more repositories and supports multiple conversation sessions.

## What Happens When You Create a Workspace

Understanding what happens behind the scenes helps you work more effectively:

<Steps>
<Step title="Git worktree is created">
Vibe Kanban creates a **git worktree** - a separate working directory with its own branch. This keeps your changes isolated from your main codebase. Your original repository remains untouched.
</Step>

<Step title="Working branch is created">
A new branch is created based on your target branch (e.g., `main`). The branch name is auto-generated based on your task (e.g., `vk/abc123-add-login-page`).
</Step>

<Step title="Agent session starts">
A coding agent is initialised and ready to receive your instructions. The agent can read files, make changes, and run commands within your workspace.
</Step>

<Step title="Setup scripts run (if configured)">
If your repository has setup scripts configured (e.g., `npm install`), they run automatically to prepare the environment.
</Step>
</Steps>

<Info>
**Where do workspaces live?** Worktrees are created in a `.vibe-kanban-workspaces` directory (configurable in Settings → General → Workspace Directory). Each workspace gets its own folder.
</Info>

## Creating a New Workspace

<Steps>
<Step title="Open the Create View">
  Click the **+** button at the top of the workspace sidebar, or use the command bar (`Cmd/Ctrl + K`) and select **New Workspace**.

  <Frame>
  <img style={{maxHeight: "300px"}} src="/images/workspaces-sidebar-create-button.png" alt="Workspace sidebar showing the plus button for creating new workspaces" />
  </Frame>
</Step>

<Step title="Select a Project">
  Choose a project from the **Project** dropdown in the right panel. Projects group related repositories together.

  <Frame>
  <img style={{maxHeight: "300px"}} src="/images/workspaces-select-project.png" alt="Project dropdown showing selected project" />
  </Frame>

  <Note>
  If you haven't created a project yet, see [Creating a New Project](#creating-a-new-project) below.
  </Note>
</Step>

<Step title="Add Repositories">
  <Frame>
  <img style={{maxHeight: "350px"}} src="/images/workspaces-add-repo.png" alt="Repository selection showing selected repo with branch dropdown and list of available repositories" />
  </Frame>

  Select which repositories to include in your workspace:

  - **Recent repositories** - Click any repo from the list to add it
  - **Browse repos on disk** - Find repositories not in the recent list
  - **Create new repo on disk** - Initialise a new git repository

  <Tip>
  You can add multiple repositories to a single workspace if your task spans multiple codebases. Each repository maintains independent git state.
  </Tip>
</Step>

<Step title="Set Target Branches">
  For each selected repository, set the **target branch** - this is the branch your changes will eventually be merged into (e.g., `main` or `develop`).

  Click the branch dropdown next to each repository to change the target branch.

  <Info>
  **Target branch vs Working branch - what's the difference?**

  - **Target branch** = Where your changes will eventually be merged (e.g., `main`). You set this.
  - **Working branch** = Where your changes are made (e.g., `vk/abc123-task-name`). Auto-created from target.

  Your changes are made on the working branch and don't affect the target until you create and merge a PR.
  </Info>
</Step>

<Step title="Describe Your Task">
  In the chat input at the bottom, describe what you want to accomplish. Be specific about:

  - What feature or fix you need
  - Any constraints or requirements
  - Files or areas of the codebase to focus on

  <Tip>
  Clear, detailed task descriptions help the agent understand your requirements and produce better results.
  </Tip>
</Step>

<Step title="Select an Agent">
  Choose which coding agent to use from the **Agent** dropdown. Available agents depend on your configuration.

  <Note>
  See [Agent Configurations](/settings/agent-configurations) for details on setting up different agents.
  </Note>
</Step>

<Step title="Create the Workspace">
  Click **Create** to start the workspace. The agent will begin working on your task immediately.
</Step>
</Steps>

## Creating a New Project

If you need to create a new project before setting up your workspace:

<Steps>
<Step title="Open the Project Dropdown">
  In the create workspace view, click the **Project** dropdown.

  <Frame>
  <img style={{maxHeight: "300px"}} src="/images/workspaces-project-dropdown.png" alt="Project dropdown showing Create new project option and list of existing projects" />
  </Frame>
</Step>

<Step title="Select Create New Project">
  Click **+ Create new project** at the top of the dropdown list.
</Step>

<Step title="Enter Project Details">
  <Frame>
  <img style={{maxHeight: "250px"}} src="/images/workspaces-create-project.png" alt="Create Project dialog with name field" />
  </Frame>

  Enter a name for your project and click **Create**.
</Step>

<Step title="Continue with Workspace Creation">
  Your new project is automatically selected. Continue adding repositories and configuring your workspace.
</Step>
</Steps>

<Note>
After creating a project, you can configure additional settings like setup scripts, dev server scripts, and cleanup scripts in the project settings. See [Projects & Repositories](/settings/projects-repositories) for more details.
</Note>

## Workspace Settings

Once a workspace is created, you can configure additional settings:

### Working Branch

The workspace automatically creates a working branch for your changes. You can view and change this in the **Git** section of the details sidebar.

### Dev Server

If your project has a dev server script configured, you can start it using:
- The **Play** icon (<Icon icon="play" />) in the context bar
- The command bar: `Cmd/Ctrl + K` → **Start Dev Server**

<Note>
Configure dev server scripts in your project settings. See [Projects & Repositories](/settings/projects-repositories) for setup instructions.
</Note>

### Workspace Notes

Use the **Notes** section in the details sidebar to document important information about the workspace - requirements, decisions, or anything you want to remember.

## Duplicating a Workspace

To create a copy of an existing workspace:

1. Open the command bar (`Cmd/Ctrl + K`)
2. Go to **Workspace Actions**
3. Select **Duplicate Workspace**

The duplicate includes the same repositories and branch configuration but starts with a fresh conversation.

## Archiving Workspaces

When you're done with a workspace, archive it to keep your workspace list clean:

**From the navbar:**
- Click the **Archive** button (<Icon icon="box-archive" />) in the top left of the navbar

**From the command bar:**
1. Press `Cmd/Ctrl + K`
2. Go to **Workspace Actions** → **Archive**

Archived workspaces can be viewed by clicking **View Archive** at the bottom of the sidebar.

<Tip>
Use the **Pin** feature to keep important active workspaces at the top of your list.
</Tip>

## Troubleshooting

<AccordionGroup>
<Accordion title="I can't see my repository in the list">
**Possible causes:**
- The repository hasn't been added to a project yet
- The folder isn't a git repository (no `.git` folder)
- The path isn't accessible

**Solutions:**
1. Click **Browse repos on disk** to manually locate the repository
2. Ensure the folder contains a `.git` directory
3. Check that Vibe Kanban has permission to access the folder
</Accordion>

<Accordion title="Workspace creation fails">
**Possible causes:**
- Git worktree creation failed (usually due to uncommitted changes in the original repo)
- Branch name conflict
- Disk space issues

**Solutions:**
1. Commit or stash any uncommitted changes in your original repository
2. Try a different target branch
3. Check available disk space (worktrees require space for a full copy of tracked files)
</Accordion>

<Accordion title="Agent doesn't start after creating workspace">
**Possible causes:**
- Agent isn't installed or configured
- API key issues
- Network connectivity problems

**Solutions:**
1. Check that your agent (e.g., Claude Code) is installed: run the CLI command manually in terminal
2. Verify API keys are configured in Settings → Agents
3. Check your internet connection
</Accordion>

<Accordion title="Setup script fails">
**Possible causes:**
- Script has errors
- Missing dependencies
- Wrong working directory

**Solutions:**
1. Test the script manually in terminal first
2. Check the Logs panel for error messages
3. Ensure paths in the script are relative to the repository root
</Accordion>
</AccordionGroup>

## Related Documentation

- [Interface Guide](/workspaces/interface) - Learn about the workspace layout and panels
- [Multi-Repo & Sessions](/workspaces/multi-repo-sessions) - Working with multiple repositories
- [Sessions](/workspaces/sessions) - Creating and managing conversation sessions
- [Command Bar](/workspaces/command-bar) - Quick actions and keyboard shortcuts
