> ## Documentation Index
> Fetch the complete documentation index at: https://commander-docs.cyshel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Isolated git worktrees for parallel development.

## Overview

Each workspace is an isolated git worktree with its own branch. This means multiple agents can work on different features simultaneously without conflicts.

## Creating Workspaces

Create workspaces in three ways:

* **From scratch** — `Cmd+N`, name it, and write an initial prompt
* **From a Linear issue** — Select a Linear issue and Commander creates a workspace linked to it
* **From a pull request** — Provide a PR URL and Commander checks out the branch

## Setup Scripts

Configure per-repository setup scripts that run when a workspace is created:

* Dependency installation (`pnpm install`)
* Database migrations
* Code generation
* Any custom setup commands

Each script has a name, command, args, timeout, and optional flag (can be skipped on failure).

## Git Integration

Commander polls git status for each workspace:

* **Files changed** — Modified, added, deleted, renamed
* **Ahead/behind** — Commits ahead of and behind the base branch
* **Conflicts** — Merge conflict detection
* **Staged/unstaged** — Separate tracking for staging area

## Linking

Workspaces can be linked to:

* **GitHub Pull Requests** — View PR details, CI checks, and review comments
* **Linear Issues** — View issue details, status, assignee, priority

## Lifecycle

| Status         | Description                    |
| -------------- | ------------------------------ |
| `initializing` | Setup scripts running          |
| `active`       | Ready and in use               |
| `paused`       | Temporarily suspended          |
| `errored`      | Setup or agent failure         |
| `archived`     | Completed, hidden from sidebar |
| `deleted`      | Worktree removed               |

## Management

* **Archive** — Hide completed workspaces (worktree preserved)
* **Unarchive** — Restore archived workspaces
* **Delete** — Remove workspace and its git worktree
* **Rename** — Change workspace display name
* **Reorder** — Drag workspaces in the sidebar

## Target Branch

Set a target branch for each workspace to control where its work will merge:

* Configure when creating the workspace or later via workspace settings
* The manager and agents are aware of the target branch for PR creation

## Setup Script Variables

Setup scripts support dynamic template variables:

| Variable               | Description                     |
| ---------------------- | ------------------------------- |
| `{{workspace.index}}`  | Numeric index of the workspace  |
| `{{workspace.branch}}` | Branch name                     |
| `{{issue.type}}`       | Type of linked Linear issue     |
| `{{issue.labels}}`     | Labels from linked Linear issue |

## Containers

Workspaces can include Docker containers for running services, databases, or dev tools:

* Add containers with a specific image, port mappings, environment variables, and volume mounts
* Configure health checks to monitor container readiness
* View container status and logs within the workspace
* Containers are automatically managed when archiving or deleting workspaces

## Environments

Workspaces can use managed development environments provisioned from `devcontainer.json`:

* **Local Docker** environments or **GitHub Codespaces**
* Auto-provisioned when the workspace is created (if enabled in repository settings)
* Port forwarding, health monitoring, and lifecycle management
* Agents can build, test, and run code inside the environment

See [Environments](/features/environments) for full details.