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

# Troubleshooting

> Common issues and how to resolve them.

## Agent Won't Start

**Symptoms:** Agent stays in "idle" or shows an error immediately after starting.

**Solutions:**

* Verify your Claude account is connected in **Settings → Account**
* Check that the repository has a valid Claude account assigned
* Ensure you have remaining API credits or an active subscription
* Try starting the agent with a different model

## Agent Rate Limited

**Symptoms:** Agent shows "rate\_limited" status and stops working.

**Solutions:**

* Wait for the rate limit to reset (shown in the agent status bar)
* Switch to a different Claude account with available capacity
* Use **Resume All** (`Cmd+K` → "Resume All Agents") to restart when limits reset
* Consider spreading work across multiple accounts

## Workspace Setup Script Failures

**Symptoms:** Workspace stuck in "initializing" with script errors.

**Solutions:**

* Check the terminal output for the specific error
* Verify the script command works when run manually in the worktree directory
* Mark scripts as optional if they're not critical (allows skipping on failure)
* Ensure all required dependencies (Node.js, pnpm, etc.) are installed

## Integration Connection Issues

**Symptoms:** GitHub, Linear, or Slack shows as disconnected.

**Solutions:**

* Go to **Settings → Integrations** and reconnect the service
* Check that your OAuth tokens haven't expired
* Ensure you have the required permissions on the connected account
* For GitHub: verify you've granted access to the specific repositories you need

## Manager Not Responding

**Symptoms:** Manager view shows no responses or stale events.

**Solutions:**

* Check that the manager is enabled in repository settings
* Verify the manager's Claude account has available capacity
* Try **Kill Manager** and restart it from the manager view
* Check the sampling interval — a very long interval means less frequent updates

## Container Pull Failures

**Symptoms:** Container stuck in "pulling" or shows error.

**Solutions:**

* Verify Docker Desktop is running on your machine
* Check that the image name is correct and accessible
* Ensure you're authenticated to private registries if needed
* Check your network connection

## Environment Provisioning Failures

**Symptoms:** Environment stuck in "provisioning", "building", or shows "errored" status.

Commander shows smart error cards with specific guidance for each failure. Common causes:

**Docker Not Available (Local mode)**

* Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) if not installed
* Start Docker Desktop — the Docker daemon must be running
* Retry provisioning from the environment panel

**GitHub Not Connected (Codespace mode)**

* Go to **Settings → Integrations** and connect your GitHub account
* Ensure you've granted access to the repository

**Codespaces Not Enabled (Codespace mode)**

* Enable Codespaces in your GitHub organization settings or repository settings
* The environment panel links directly to the relevant settings page

**Branch Not on Remote (Codespace mode)**

* Push the workspace branch to GitHub before creating a codespace
* Commander attempts this automatically but it can fail if the remote is misconfigured

**gh CLI Not Installed (Codespace mode)**

* Install from [cli.github.com](https://cli.github.com) and run `gh auth login`
* The `gh` CLI is optional but required for running commands and syncing files inside codespaces

**No GitHub Remote**

* Add a GitHub remote: `git remote add origin <url>`
* This is required for both Codespace creation and branch pushing

## High Token Usage

**Symptoms:** Costs higher than expected.

**Solutions:**

* Set a **daily budget** in repository settings to cap spending
* Configure **budget alert thresholds** (default: 50%, 80%, 100%)
* Use lower effort levels for less critical tasks
* Use Haiku instead of Opus for simple tasks
* Monitor per-agent costs in the workspace detail view

## App Not Updating

**Symptoms:** Commander doesn't install the latest version.

**Solutions:**

* Check **Settings → General → Check for Updates** is enabled
* Enable **Auto-Download Updates** for automatic installation
* Manually check by going to **Settings → About**
* Download the latest version directly from [commander.cyshel.com](https://commander.cyshel.com)

## Resetting Commander

If Commander is in a bad state, you can reset:

1. **Clear manager history** — Settings → Agent → Clear Manager History (per repository)
2. **Restart the app** — Quit and relaunch Commander
3. **Reset data** — Delete the Commander data directory at `~/Library/Application Support/Commander/`

<Warning>
  Resetting data removes all conversations, settings, and workspace state. Your git repositories and
  worktrees are not affected.
</Warning>