Claude Squad defaults to using claude (Claude Code) for all sessions. But you don't always want the same tool for every task — some tasks flow better with Codex, some you want to try with Aider, sometimes you just want to switch to Gemini CLI and see how it performs.

Configure profiles and you can choose which tool to use when creating each session, without having to edit the config file or remember startup commands every time.

Where to Find the Config File

cs debug

This command prints the full path to the config file, usually:

~/.claude-squad/config.json

If the file doesn't exist yet, it will be automatically created the first time you run cs. Open it with your preferred editor:

code ~/.claude-squad/config.json
# or
vim ~/.claude-squad/config.json

What the Default Config Looks Like

Without any modifications, the config file looks something like this:

{
  "default_program": "claude"
}

That's it. default_program is the program used by default when creating new sessions each time you run cs.

Setting Up Multiple Profiles

If you want to switch between multiple AI tools, add a profiles array:

{
  "default_program": "claude",
  "profiles": [
    { "name": "claude", "program": "claude" },
    { "name": "codex", "program": "codex" },
    { "name": "gemini", "program": "gemini" },
    { "name": "aider", "program": "aider --model ollama_chat/gemma3:1b" }
  ]
}

Each profile has two fields:

Field	Description
`name`	The name shown in the profile selector
`program`	The actual command to run

Once configured, the next time you press N to create a new session, Claude Squad shows a profile selector where you can use ←/→ to choose which tool to use.

Environment Variables for Each Tool

Different AI tools require different API keys — set these up before using Claude Squad:

Claude Code:

# Claude Code has its own login flow, no manual API key needed
# Just log in once with the claude command

Codex (OpenAI):

export OPENAI_API_KEY="sk-..."

Gemini CLI:

export GEMINI_API_KEY="..."
# Or use Google Cloud authentication

Aider (Ollama local models):

# Need to run Ollama first
ollama pull gemma3:1b

It's worth adding these export statements to ~/.zshrc or ~/.zshenv so they're automatically loaded every time you open a terminal, without needing to set them manually each time.

Practical Profile Configuration Examples

Configured by Use Case

{
  "default_program": "claude",
  "profiles": [
    {
      "name": "claude",
      "program": "claude"
    },
    {
      "name": "codex",
      "program": "codex"
    },
    {
      "name": "aider-local",
      "program": "aider --model ollama_chat/llama3.2"
    },
    {
      "name": "aider-gpt4",
      "program": "aider --model gpt-4o"
    }
  ]
}

This gives you four options: Claude Code (daily driver), Codex (occasional use), Aider with a local model (offline or cost-saving), and Aider with GPT-4o (when you need more capability).

Testing Different Models

If you're evaluating different AI tools, you can open multiple sessions at once, each using a different profile, give them the same task, and compare output quality — Claude Squad's diff view makes comparison very convenient.

Config Changes Take Effect Immediately

Modifications to the config file take effect immediately — the next time you create a new session, Claude Squad reads the latest config. No restart required.

Launching with a Specific Profile

If you know this entire work session will use a specific tool, you can specify it at launch:

# All sessions use codex
cs -p "codex"
 
# Use a specific aider command
cs -p "aider --model gpt-4o --no-auto-commits"

The -p flag takes priority over default_program in the config file and doesn't affect your config file.

FAQ

Q: Can I run a claude session and a codex session simultaneously within the same Claude Squad process?

Yes. You can choose a different profile for each session when creating it, and they run in their own worktrees without interfering with each other.

Q: What can go in the program field of profiles?

Any command that can be run directly in a terminal — including commands with arguments, like aider --model gpt-4o --no-auto-commits. Claude Squad runs that string directly inside the tmux session.

With profiles configured, the next step is mastering the complete review and push workflow — after the agent finishes, how to review, confirm, and ship it.

Previous: Multi-Agent Parallel Development: Designing a Workflow for Three Simultaneous Tasks Next: Review, Commit, Push: The Complete Post-Agent Review Workflow