claude-squad Documentation

Technical Documentation: smtg-ai/claude-squad

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Claude Squad [](https://github.com/smtg-ai/claude-squad/actions/workflows/build.yml) [](https://github.com/smtg-ai/claude-squad/releases/latest)

Claude Squad is a terminal app that manages multiple Claude Code, Codex, Gemini (and other local agents including Aider) in separate workspaces, allowing you to work on multiple tasks simultaneously.

Highlights Copy Section

• Complete tasks in the background (including yolo / auto-accept mode!)
• Manage instances and tasks in one terminal window
• Review changes before applying them, checkout changes before pushing them
• Each task gets its own isolated git workspace, so no conflicts

https://github.com/user-attachments/assets/aef18253-e58f-4525-9032-f5a3d66c975a

Installation Copy Section

Both Homebrew and manual installation will install Claude Squad as cs on your system.

Homebrew

brew install claude-squad
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"

Manual

Claude Squad can also be installed by running the following command:

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

This puts the cs binary in ~/.local/bin.

To use a custom name for the binary:

curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash -s -- --name <your-binary-name>

Prerequisites Copy Section

• tmux
• gh

Usage Copy Section

Usage:
  cs [flags]
  cs [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  debug       Print debug information like config paths
  help        Help about any command
  reset       Reset all stored instances
  version     Print the version number of claude-squad

Flags:
  -y, --autoyes          [experimental] If enabled, all instances will automatically accept prompts for claude code & aider
  -h, --help             help for claude-squad
  -p, --program string   Program to run in new instances (e.g. 'aider --model ollama_chat/gemma3:1b')

Run the application with:

cs

NOTE: The default program is claude and we recommend using the latest version.

Using Claude Squad with other AI assistants:

• For Codex: Set your API key with export OPENAI_API_KEY=<your_key>
• Launch with specific assistants:
  • Codex: cs -p "codex"
  • Aider: cs -p "aider ..."
  • Gemini: cs -p "gemini"
• Make this the default, by modifying the config file (locate with cs debug)

Menu

The menu at the bottom of the screen shows available commands:

Instance/Session Management

• n - Create a new session
• N - Create a new session with a prompt
• D - Kill (delete) the selected session
• ↑/j, ↓/k - Navigate between sessions

Actions

• ↵/o - Attach to the selected session to reprompt
• ctrl-q - Detach from session
• s - Commit and push branch to github
• c - Checkout. Commits changes and pauses the session
• r - Resume a paused session
• ? - Show help menu

Navigation

• tab - Switch between preview tab and diff tab
• q - Quit the application
• shift-↓/↑ - scroll in diff view

Configuration Copy Section

Claude Squad stores its configuration in ~/.claude-squad/config.json. You can find the exact path by running cs debug.

Profiles

Profiles let you define multiple named program configurations and switch between them when creating a new session. When more than one profile is defined, the session creation overlay shows a profile picker that you can navigate with ←/→.

To configure profiles, add a profiles array to your config file and set default_program to the name of the profile to select by default:

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

Each profile has two fields:

If no profiles are defined, Claude Squad uses default_program directly as the launch command (the default is claude).

FAQs Copy Section

Failed to start new session

If you get an error like failed to start new session: timed out waiting for tmux session, update the
underlying program (ex. claude) to the latest version.

How It Works Copy Section

1. tmux to create isolated terminal sessions for each agent
2. git worktrees to isolate codebases so each session works on its own branch
3. A simple TUI interface for easy navigation and management

License Copy Section

AGPL-3.0

Star History Copy Section

Overview (`web/README.md`) Copy Section

This is a Next.js project bootstrapped with create-next-app.

Getting Started Copy Chapter

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Learn More Copy Chapter

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel Copy Chapter

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~1686 tokens
• Canonical Reference: https://codewiki.google/github.com/smtg-ai/claude-squad