Skip to main content

​
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 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 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

​
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/
Resetting data removes all conversations, settings, and workspace state. Your git repositories and worktrees are not affected.