claude-squad

Claude Squad is a terminal application for managing multiple AI terminal agents in separate Git workspaces, supporting local agents such as Claude Code, Codex, Gemini, Aider, OpenCode, and Amp, so that multiple tasks can be advanced simultaneously.

Main Capabilities

• Complete tasks in the background, including yolo / auto-accept mode.
• Manage multiple instances and tasks in one terminal window.
• Review changes before applying them, and check out changes before pushing.
• Each task has its own separate Git workspace to avoid conflicts.

Installation and Startup

When installing via Homebrew or manually, Claude Squad is installed into the system with the cs command. You can also run the following command to install it, placing the cs binary into ~/.local/bin:

If you want to use a custom name for the binary, you can name it yourself. Use csto start the application.

Note: The default program is claude, and using the latest version is recommended.

Working with Other AI Assistants

• For Codex: set the API key export OPENAI_API_KEY=<your_key>
• Start a specific assistant:
  • Codex:cs -p "codex"
  • Aider：cs -p "aider ..."
  • Gemini：cs -p "gemini"

You can set a specific assistant as the default by modifying the configuration file (locate it using cs debug ).

Interface Operations

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

• n — Create a new session
• N — Create a new session with a prompt
• D — Terminate (delete) the selected session
• ↑/j、↓/k — Navigate between sessions
• ↵/o — Attach to the selected session to prompt again
• ctrl-q — Detach from the session
• s — Commit and push the branch to GitHub
• c — Checkout. Commit changes and pause the session
• r — Resume a paused session
• ? — Show the help menu
• tab — Switch between the preview tab and the diff tab
• q — Quit the application
• shift-↓/↑ — Scroll in the diff view

Configuration and Configuration File

Claude Squad stores its configuration in ~/.claude-squad/config.json. Run cs debug to see the exact path.

Profiles allow you to define multiple named program configurations and switch between them when creating a new session. When multiple profiles are defined, the session creation overlay displays a profile selector, which can be navigated with ← / → .

To configure profiles, add a profiles array to the configuration file, and set default_program to the name of the profile selected by default. Each profile has two fields.

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

Limitations and Troubleshooting

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

Technical Implementation

• Use tmux to create an isolated terminal session for each agent.
• Use git worktrees to isolate the codebase, so that each session works on its own branch.
• Provide a simple TUI interface for easy navigation and management.