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
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 fromdevcontainer.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