Deep Dive — Session Manager

Claude Squad

A terminal app that manages multiple AI coding agents in separate workspaces. One screen to rule them all — Claude Code, Codex, Aider, Gemini, running in parallel without stepping on each other.

smtg-ai Creator

Go Language

6.1k+ GitHub Stars

AGPL-3.0 License

Overview

What Is Claude Squad?

Claude Squad is a lightweight TUI (text user interface) that lets you run multiple AI coding agents simultaneously, each in its own isolated Git workspace. Instead of juggling terminal windows and branches manually, you get a single dashboard to spawn, monitor, pause, resume, and merge agent sessions.

The core idea is practical: each agent gets its own git worktree, so agents never interfere with each other's changes. You supervise from a unified interface, review diffs inline, and choose when to commit and push. It is not an orchestration framework — it is a session manager that makes running parallel agents feel natural.

Claude Squad manages multiple Claude Code sessions in parallel. Each agent gets its own isolated Git workspace — essentially multiplying output by the number of active agents.

— Addy Osmani, "Coding for the Future Agentic World"

Under the Hood

Architecture

Three building blocks: tmux for terminal isolation, git worktrees for code isolation, and a Go-based TUI for the control plane.

┌──────────────────────────────────────────────────────────┐
│                  Claude Squad TUI                        │
│  Session List  │  Preview Pane  │  Diff View       │
├──────────────────────────────────────────────────────────┤
│                   tmux layer                             │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐        │
│  │session1│  │session2│  │session3│  │session4│        │
│  │ claude  │  │  codex  │  │  aider  │  │ gemini  │        │
│  └────┬───┘  └────┬───┘  └────┬───┘  └────┬───┘        │
├───────┼──────────┼──────────┼──────────┼────────────────┤
│       v          v          v          v                │
│  git worktree  worktree   worktree   worktree         │
│  branch-a     branch-b   branch-c   branch-d         │
└──────────────────────────────────────────────────────────┘

☰

tmux Sessions

Each agent runs in its own tmux session, providing full terminal isolation. Sessions persist even if you quit the TUI — agents keep working.

⎇

Git Worktrees

Every session gets its own git worktree on a separate branch. No merge conflicts between concurrent agents. Changes stay isolated until you explicitly merge.

▣

TUI Control Plane

A lightweight terminal interface to create, monitor, pause, resume, and delete sessions. Preview agent output and diffs without switching windows.

Getting Started

Installation & Setup

Multiple installation methods. The binary is called cs.

Prerequisites

tmux — terminal multiplexer (required)
gh — GitHub CLI (required for push/PR features)
At least one AI coding agent installed (Claude Code, Codex, Aider, Gemini)

Option 1: Homebrew

      brew install claude-squad

# Create the short alias (recommended)
ln -s "$(brew --prefix)/bin/claude-squad" "$(brew --prefix)/bin/cs"
    

Option 2: Install Script

      # Downloads and installs the cs binary to ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash

# Custom binary name
curl -fsSL ... | bash -s -- --name my-squad
    

Launch

      # Start with default agent (Claude Code)
cs

# Start with a specific agent
cs -p "codex"
cs -p "aider --model sonnet"
cs -p "gemini"

# Auto-accept mode (experimental)
cs -y
    

Capabilities

Key Features

What makes Claude Squad useful for parallel AI development.

⏵

Background Execution

Agents run in tmux sessions that persist independently. Close the TUI, agents keep working. Come back later to check results.

⎇

Workspace Isolation

Git worktrees give each agent its own copy of the codebase on a separate branch. Zero conflict between parallel tasks.

≡

Unified Dashboard

One terminal to see all sessions: status, preview output, scroll through diffs. No more juggling tmux windows manually.

⇄

Multi-Agent Support

Not locked to Claude Code. Run Codex, Aider, Gemini, or any terminal-based agent. Mix and match in the same session.

⚡

YOLO Mode

The -y flag auto-accepts all agent prompts. Experimental, but useful for trusted workflows where you want full autonomy.

↑

Commit & Push

Review changes in the diff tab, then commit and push the branch with a single keystroke. Checkout pauses the session cleanly.

Compatibility

Supported Agents

Any terminal-based AI coding agent works. These are the officially documented ones.

Claude Code

Default agent

OpenAI Codex

cs -p "codex"

Requires OPENAI_API_KEY

Aider

cs -p "aider ..."

Any Aider config

Gemini

cs -p "gemini"

Google Gemini CLI

Set a default agent program via the config file. Locate it with: cs debug

Controls

Keyboard Shortcuts

The TUI is entirely keyboard-driven. These are the core bindings.

Session Management

Key	Action
`n`	New session (spawns a new agent in a fresh worktree)
`N`	New session with an initial prompt
`D`	Delete the selected session
`j` / `k`	Navigate between sessions (or arrow keys)

Actions

Key	Action
`Enter` / `o`	Attach to session (takes over the terminal, can reprompt)
`Ctrl-q`	Detach from an attached session back to the dashboard
`s`	Commit changes and push the branch
`c`	Checkout — commit, push, and pause the session
`r`	Resume a paused session
`?`	Show help menu

Navigation

Key	Action
`Tab`	Toggle between preview and diff tabs
`Shift+Up` / `Shift+Down`	Scroll the diff view
`q`	Quit Claude Squad (agents keep running in tmux)

In Practice

Example Workflow

Modernizing a legacy codebase with three parallel agents, each handling a different subsystem.

Launch Claude Squad

Navigate to your repository and start the TUI. It detects the git repo and is ready to spawn sessions.

cd ~/projects/my-app && cs

Spawn Three Sessions

Press N three times to create sessions with prompts:

"Upgrade React from v17 to v19, fix all breaking changes"

"Refactor the database layer to use Prisma instead of raw SQL"

"Add comprehensive test coverage for the API routes"

Monitor From the Dashboard

Use j/k to navigate between sessions. The preview pane shows live agent output. Press Tab to see the running diff of changes. All three agents are working in isolated worktrees.

Intervene When Needed

If an agent gets stuck or needs clarification, press Enter to attach to its session. Type your response directly. Press Ctrl-q to detach back to the dashboard.

Review and Push

When an agent finishes, review its diff in the Tab view. Press s to commit and push the branch. Open a PR from the pushed branch. Repeat for each session.

Walk Away

Press q to quit the TUI. Agents keep running in their tmux sessions. Run cs later to reconnect and check progress.

The human must still partition work and review outputs — best practices for multi-agent coordination remain an evolving area.

— Addy Osmani

Trade-offs

Limitations & Trade-offs

Claude Squad is a session manager, not an orchestration framework. Know the boundaries.

No automatic task coordination. You decide what each agent works on. There is no supervisor agent distributing tasks or resolving overlaps.
Manual merge resolution. Each agent works on a separate branch, but merging those branches back together is your responsibility.
Human partitioning required. You must decompose work into independent tasks. Agents that need to touch the same files will create merge conflicts.
No built-in CI integration. Unlike Multiclaude's auto-merge-on-CI-pass, Claude Squad does not automatically validate or merge changes.
Token consumption scales linearly. Each session is a full AI agent instance. Three sessions means three times the API or subscription usage.
tmux dependency. Requires tmux to be installed and working. Some tmux version mismatches can cause session startup failures.
AGPL-3.0 license. The copyleft license may be restrictive for some commercial use cases.

Claude Squad vs. Multiclaude vs. Conductor

Dimension	Claude Squad	Multiclaude	Conductor
Type	Session manager	Orchestration framework	Desktop GUI
Agent Support	Any terminal agent	Claude Code only	Claude Code
Task Coordination	Manual (human)	Automatic (supervisor)	Manual (visual)
Auto-Merge	No	Yes (CI-gated)	No
Interface	Terminal TUI	CLI + tmux	Mac desktop app
License	AGPL-3.0	MIT	Commercial
Best For	Parallel manual sessions	Autonomous CI-driven flow	Visual branch management

Resources