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

# Core Concepts

> The building blocks of Commander: Repository, Workspace, Agent, Manager, Goal, Container, Environment, and Tracing.

## Repository

A git repository on your local filesystem. Commander creates isolated worktrees within it for each workspace.

* Has its own settings (default model, budget, manager config)
* Can be assigned a specific Claude account
* Has a manager hierarchy (one root manager, optional project sub-managers)

## Workspace

An isolated git worktree created from a repository. Each workspace has its own branch and one or more agents working in it.

* Created from scratch, from a Linear issue, or from a GitHub PR
* Runs setup scripts on creation (e.g., dependency installation)
* Shows live git status (files changed, ahead/behind, conflicts)
* Can be linked to a Linear issue and/or a GitHub pull request
* Assigned to a manager (root manager by default, or a project sub-manager)
* Can be archived when complete, or deleted to remove the worktree

## Agent

An AI agent running within a workspace. Agents execute your prompts, use tools, edit files, and report progress in real time.

* You can see every message, tool call, and file edit as it happens
* Tracks token usage, cost (including overage), and context window fill
* Supports plan mode (proposes steps for your approval before executing)
* Messages queue automatically when the agent is busy
* Sessions persist across app restarts
* Can be warmed up for faster initial response

## Manager

A recursive manager hierarchy (one root manager per repository, with optional project sub-managers) that coordinates work across all your workspaces and agents.

* **Root manager** — One per repository. Monitors all agents and workspaces. Cannot be deleted.
* **Project managers** — Optional sub-managers for scoping work into named groups, each owning a subset of workspaces. Can be deleted, reparented, or have workspaces reassigned.
* Monitors agent completions, errors, rate limits, and questions
* Manages goals with hierarchical task tracking
* Can create workspaces, manage agents, and send Slack messages
* Provides suggested actions as clickable buttons in the UI
* Periodically reflects on progress

## Goal

A trackable objective managed by the manager.

* Supports hierarchical structure (parent goals with sub-goals)
* Can be linked to a workspace, agent, Linear issue, or pull request
* Tracks status from pending through completed or cancelled
* Supports images with captions and rich descriptions

## Container

A Docker container managed within a workspace for running services, databases, or dev dependencies.

* Supports image pulling, port mapping, environment variables, volume mounts, and health checks
* Full lifecycle management: create, pull, start, stop, restart, remove
* Logs viewable within Commander

## Environment

A managed development environment provisioned from a `devcontainer.json` configuration.

* Two modes: **Local Docker** (runs containers on your machine) or **GitHub Codespaces** (remote cloud environment)
* Configured per-repository in Settings → Environments
* Auto-provisions when new workspaces are created (optional)
* Includes port forwarding, health monitoring, and lifecycle management
* Agents can build, test, and run code inside the environment

## Tracing

A built-in observability system for understanding agent performance.

* View trace summaries per agent with duration, span count, and error count
* Drill into individual spans to see timing, attributes, and events
* Aggregate tool call statistics: call count, average duration, error rate
* Identify bottlenecks with slowest-span and error-span queries
* Helps debug why agents take longer than expected or encounter failures