Documentation

Commander is a native Mac app that wraps your coding agents in a review loop. You prompt the agent, see what it changed, and commit what's good — all in one place.

It connects to agent CLIs you already have installed (Claude Code, Codex, OpenCode, Pi) and adds diffs, git workflow, and project management on top.

Note: This page covers setup, configuration, and troubleshooting. Feature walkthroughs and screenshots will be expanded over time.

You need three things:

• macOS 15.0 or later — Commander is a native Swift app built on modern macOS APIs
• One supported agent CLI — installed and authenticated. See setup links below.
• That's it — no accounts, no cloud services, no extra dependencies.

Commander talks to these agent CLIs. Install one, authenticate it in your terminal, and Commander picks it up automatically:

• 
  Claude Code — Setup docs: docs.anthropic.com/en/docs/claude-code
• 
  Codex — Setup docs: github.com/openai/codex
• 
  OpenCode — Install and authenticate using your OpenCode provider documentation.
• 
  Pi — Install and authenticate using your Pi provider documentation.

Commander doesn't touch your credentials. Your agent CLI handles all authentication — API keys, SSO, OAuth, whatever the provider uses.

Commander never sees or stores your API keys.

How it works

Authenticate your CLI in Terminal first. Commander uses that existing session. If auth fails inside Commander, just re-run the CLI in Terminal and sign in there — Commander will pick it up.

Open Commander → Settings (or ⌘,) to tell Commander where your CLI lives and how to run it.

CLI Path

Commander needs to know where your agent CLI binary lives. It checks the usual places (/opt/homebrew/bin/, /usr/local/bin/) automatically.

• Detect — Click to automatically find the CLI on your system
• Manual path — Enter the full path if auto-detection doesn't work

To find your CLI path manually, run one of the following in Terminal:

• which <your-cli-binary> (for example, which claude or which codex)

Environment Variables

You can pass custom environment variables to the CLI process. This is useful for:

• Setting API keys (for example, provider-specific API key variables your CLI expects)
• Configuring proxy settings
• Custom CLI configuration

Use the + and − buttons to add or remove environment variables.

AWS Bedrock (custom model ARNs)

Claude Code can talk to AWS Bedrock by using a Bedrock model ARN (often an inference profile ARN) as the configured model. You can see what your Claude Code CLI uses in ~/.claude/settings.json:

jq -r '.model' ~/.claude/settings.json

Example value:

"arn:aws:bedrock:eu-west-1:xxxxxxxxxxxx:application-inference-profile/yyyyyyyyyyy"

When you launch Claude Code with a Bedrock ARN, it will authenticate with AWS (typically via AWS SSO).

Commander selects the model based on the menu bar dropdown (Sonnet / Opus / Haiku). If you want those selections to route to Bedrock, override the default model identifiers Claude Code uses for each selection by setting these environment variables in Commander:

• ANTHROPIC_DEFAULT_SONNET_MODEL
• ANTHROPIC_DEFAULT_OPUS_MODEL
• ANTHROPIC_DEFAULT_HAIKU_MODEL

Recommended setup:

1. Copy your Bedrock ARN from ~/.claude/settings.json.
2. In Commander → Settings → Environment Variables, add ANTHROPIC_DEFAULT_SONNET_MODEL and set it to the ARN.
3. Select Sonnet in Commander's menu bar model dropdown.

If you also set ANTHROPIC_DEFAULT_OPUS_MODEL and/or ANTHROPIC_DEFAULT_HAIKU_MODEL to the same ARN, you can switch between Sonnet/Opus/Haiku in Commander while still using Bedrock for all of them.

If you see 400 The provided model identifier is invalid., it usually means Commander is still sending a non-Bedrock model identifier; verify the corresponding ANTHROPIC_DEFAULT_*_MODEL variable is set for the model you selected in the menu bar.

Agent Profiles let you keep multiple setups for the same provider. A profile can have its own CLI path, default model, reasoning setting, extra CLI flags, and custom environment variables. This is the easiest way to separate work and personal accounts, point one profile at cloud credentials and another at local models, or keep different config homes for the same CLI.

Where to manage profiles

• Commander → Settings → Agents shows the profile list on the left and the selected profile's settings on the right.
• Use the + button to add a new profile for Claude, Codex, OpenCode, or Pi.
• Double-click a profile name to rename it. Use the context menu to duplicate an existing profile.
• Use the − button to delete a profile. This removes Commander's saved profile metadata, but it does not delete the external CLI's own config directory.

How Commander picks a profile

1. If you start New Chat with… from the Projects list, that explicit profile is used for the session.
2. If the project has a Preferred Profile in Project Settings, Commander uses that for new chats in that project.
3. Otherwise Commander uses the app-wide Default Profile.

Project-level preferred profiles are set in Project Settings → General → Preferred Profile. Choose Use Global Default to inherit the global setting again.

What a profile can change

• CLI path
• Default model
• Extra CLI flags
• Environment variables

Commander stores only the profile metadata. Authentication and provider-specific files still live in the underlying CLI's own config directory.

Separate work and personal setups

If you want one profile per account or environment, the simplest approach is to point each provider at a different config directory using the profile's environment variables.

• Claude: CLAUDE_CONFIG_DIR=~/.claude-work
• Codex: CODEX_HOME=~/.codex-work
• OpenCode: set XDG directories such as XDG_CONFIG_HOME and XDG_DATA_HOME
• Pi: PI_CODING_AGENT_DIR=~/.pi-work/agent

Use Extra CLI flags when you want to pass provider-specific arguments on top of that, such as a custom settings file or session directory.

# Examples
CLAUDE_CONFIG_DIR=~/.claude-work
CODEX_HOME=~/.codex-work
XDG_CONFIG_HOME=~/.config/opencode-work
PI_CODING_AGENT_DIR=~/.pi-work/agent

References: Claude Code, Codex, OpenCode, Pi

Actions are user-defined scripts you can run from the toolbar Run button and the Actions menu.

They are configured per project/worktree in .commander/actions.json.

Configuration File

{
  "actions": [
    {
      "name": "Run",
      "script": "actions/2F0B4A6D-A8C9-47B7-9505-650C31234C50.sh",
      "icon": "play.fill",
      "background": false
    }
  ]
}

• name: display name in the toolbar and menu (also used for worktree override matching)
• script: script path, relative to the .commander/ folder
• icon: optional SF Symbol name shown in the menu/toolbar
• background: if true, run as a background process; if false, run in the terminal pane

If background is omitted, Commander treats it as false.

Script Path Rules

• Relative paths resolve from the .commander/ directory that contains actions.json.
• Absolute paths are supported.
• Tilde paths like ~/scripts/run.sh are expanded to your home directory.

By convention, Commander creates new script paths using UUID filenames under .commander/actions/.

Project vs Worktree Resolution

1. Commander loads project-level actions first.
2. Commander then loads worktree-level actions and overrides project actions with the same name.
3. If an action named Run exists, Commander places it first.

Action Environment Variables

Commander injects these variables for every action script:

• COMMANDER_ACTION_NAME
• COMMANDER_WORKSPACE_PATH
• COMMANDER_CONTEXT_NAME
• COMMANDER_CONTEXT_TYPE (project or worktree)
• COMMANDER_BRANCH (for git contexts)

Terminal actions receive these as inline command-scoped variables. Background actions receive them via process environment variables.

Authoring Scripts in Commander

• The Actions editor can create/edit scripts inline.
• New scripts start with a #!/bin/zsh template.
• On save, Commander creates parent folders as needed and sets script permissions to executable (755).

CLI not found

If Commander can't find your CLI, check that it works in your terminal first:

• Run <your-cli-binary> --version to verify installation.
• If it's not installed, use the setup guidance in Supported Agents.

Authentication issues

Auth broken? Run your CLI directly in Terminal to re-authenticate:

• Run <your-cli-binary> and complete the provider login flow.

Commander piggybacks on your CLI's auth session. Fix it in Terminal, and it's fixed in Commander.

Is my code sent anywhere?

Not by Commander. Your agent CLI may send code context to its provider — that's between you and the provider, not Commander.

How do I update?

Download the latest version from the download section or run brew upgrade commander. Commander tells you when an update is available.

See the changelog for what shipped recently.

Using AWS Bedrock

If you're using Claude via an AWS Bedrock model ARN, see Configuration → AWS Bedrock (custom model ARNs) for the recommended ANTHROPIC_DEFAULT_*_MODEL environment variable setup.

Actions menu is empty

Create .commander/actions.json in your project or worktree and add at least one valid action entry. You can also open Actions → Edit Actions... from the toolbar menu to create one.

Action script does not run

• Check that script points to the expected file relative to .commander/, or use an absolute path.
• Confirm the script starts with a valid shebang like #!/bin/zsh.
• Ensure the file is executable if created outside Commander: chmod +x /path/to/script.sh.

Config error in Actions menu

If Commander shows a project/worktree config error in the Actions menu, validate .commander/actions.json for JSON syntax and field type issues.