Skip to main content

​
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

​
Sharing

Right-click a workspace and choose Share… to control who can see it and what they can do. Who can see it What they can do — pick a level for the whole org, or per person: Adding someone individually can give them more than the org-wide level — useful for sharing a read-only workspace with one collaborator. You always keep admin on workspaces you create, and your organization’s owners and admins do too, so you can’t lock yourself out. A private workspace shows a lock icon in the sidebar. Defaults for new workspaces are set in Settings → Organization → Default visibility for new workspaces, and a repository can override it. Changing a default only affects workspaces created afterwards. If someone removes your access, your local checkout stays on your machine — it just stops syncing, and the sidebar marks it as a local copy.

​
Management

  • Archive — Hide completed workspaces (worktree preserved)
  • Unarchive — Restore archived workspaces
  • Delete — Remove workspace and its git worktree
  • Rename — Change workspace display name
  • Share — Set visibility and per-person access (see Sharing)
  • 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:

​
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 for full details.