If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/smtg-ai/claude-squad shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 6w ago
• 14 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live smtg-ai/claude-squad repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/smtg-ai/claude-squad.

What it runs against: a local clone of smtg-ai/claude-squad — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in smtg-ai/claude-squad | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 70 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of smtg-ai/claude-squad. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/smtg-ai/claude-squad.git
#   cd claude-squad
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of smtg-ai/claude-squad and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "smtg-ai/claude-squad(\\.git)?\\b" \\
  && ok "origin remote is smtg-ai/claude-squad" \\
  || miss "origin remote is not smtg-ai/claude-squad (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "app/app.go" \\
  && ok "app/app.go" \\
  || miss "missing critical file: app/app.go"
test -f "session/instance.go" \\
  && ok "session/instance.go" \\
  || miss "missing critical file: session/instance.go"
test -f "session/tmux/tmux.go" \\
  && ok "session/tmux/tmux.go" \\
  || miss "missing critical file: session/tmux/tmux.go"
test -f "session/git/worktree.go" \\
  && ok "session/git/worktree.go" \\
  || miss "missing critical file: session/git/worktree.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 70 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~40d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/smtg-ai/claude-squad"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Claude Squad is a terminal multiplexer that manages multiple AI coding agents (Claude Code, Codex, Gemini, Aider) in isolated tmux workspaces, enabling parallel task execution with separate git repositories per task. It solves the problem of running multiple AI assistants simultaneously without conflicts, allowing developers to queue tasks, review changes, and selectively apply them—with optional auto-accept mode for hands-free execution. Single-binary Go application organized by domain: cmd/ handles CLI argument parsing, app/ contains main orchestration logic, session/ manages tmux multiplexing and git worktree isolation, config/ handles user configuration and state, daemon/ provides background process capabilities, keys/ manages key handling, and log/ provides logging. Each AI agent runs in its own tmux session with a dedicated git worktree under session/git/.

Software developers and DevOps engineers who want to parallelize AI-assisted coding tasks (like code generation, refactoring, or bug fixes) across multiple AI agents in a single terminal interface, particularly those using Claude Code or open-source alternatives like Aider who need background task management and conflict-free git workflows.

Actively developed and production-ready. The repo uses Go 1.23+ with a CI/CD pipeline (build, lint, release, deploy-pages workflows via GitHub Actions), includes unit tests across core modules (app_test.go, config_test.go, tmux_test.go), and publishes releases via .goreleaser.yaml. However, it's relatively young with modest GitHub presence and relies on external tools (tmux, gh CLI) as hard prerequisites.

Low-to-moderate risk. Dependencies are well-maintained (charmbracelet/bubbletea for TUI, go-git/go-git for git operations, cobra for CLI), and the Go standard library handles most I/O. Main risk is platform-specific code duplication (daemon_unix.go, daemon_windows.go, tmux_unix.go, tmux_windows.go) which increases maintenance burden for cross-platform bugs. Single apparent maintainer (smtg-ai org) and external dependency on tmux availability could be operational risks.

Based on file structure, active areas include: tmux session management (session/tmux/), git worktree operations (session/git/worktree_*.go suggesting branch and operation management), configuration state (config/state.go), and CLI enhancements (cmd/cmd.go). The presence of experimental flags like --autoyes in the README suggests active feature development around autonomous task acceptance.

Clone and install via the provided shell script: curl -fsSL https://raw.githubusercontent.com/smtg-ai/claude-squad/main/install.sh | bash (installs to ~/.local/bin), or brew install claude-squad && ln -s $(brew --prefix)/bin/claude-squad $(brew --prefix)/bin/cs for Homebrew. Requires tmux and gh CLI pre-installed. Run with cs after ensuring claude (Claude Code) is in PATH, or specify an agent: cs -p "aider --model ollama_chat/gemma3:1b".

Daily commands: Build: go build -o cs . from repository root (outputs cs binary). Run: ./cs (launches interactive TUI), ./cs -p "codex" (launch with specific agent), ./cs --autoyes -p "aider" (auto-accept mode). Debug config paths: ./cs debug. View version: ./cs version. Requires tmux session support and gh CLI in PATH.

• main.go — Application entry point that initializes the CLI and daemon; every contributor must understand the startup flow.
• app/app.go — Core application state and lifecycle management for the TUI; the main business logic hub for all agent orchestration.
• session/instance.go — Defines the Instance abstraction representing a single AI agent workspace; critical for understanding multi-agent isolation.
• session/tmux/tmux.go — Terminal multiplexer integration that manages separate pseudo-terminal sessions for each agent; load-bearing for task isolation.
• session/git/worktree.go — Git worktree management ensuring each agent gets its own isolated git workspace; prevents merge conflicts between parallel tasks.
• cmd/cmd.go — CLI command definitions and routing using Cobra; entry point for understanding command structure and argument parsing.
• ui/terminal.go — Main TUI renderer and event loop using Bubble Tea; responsible for rendering the multi-instance dashboard.

Add support for a new AI agent/CLI tool

1. Define a new instance type in config/config.go and add profile schema (config/config.go)
2. Create initialization logic in cmd/cmd.go to spawn new instances of your agent (cmd/cmd.go)
3. Register keybindings and commands in keys/keys.go if your agent has unique shortcuts (keys/keys.go)
4. Extend app/app.go's instance management logic to handle your agent's lifecycle events (app/app.go)

Add a new TUI overlay/modal dialog

1. Create a new file in ui/overlay/ following the pattern of confirmationOverlay.go or textInput.go (ui/overlay/overlay.go)
2. Implement the Bubble Tea Model interface (Init, Update, View) (ui/overlay/textOverlay.go)
3. Register the overlay trigger in ui/terminal.go's Update method (ui/terminal.go)
4. Add styling constants to ui/consts.go for your overlay's appearance (ui/consts.go)

Extend git operations for instances (e.g., new branch workflows)

1. Add new worktree operation functions in session/git/worktree_ops.go (session/git/worktree_ops.go)
2. Update Instance type in session/instance.go to expose new git methods (session/instance.go)
3. Wire the new operation into app.go's instance context menu or status display (app/app.go)
4. Add keybinding in keys/keys.go to trigger the operation from the TUI (keys/keys.go)

Add a new tmux session feature (e.g., custom pane layout)

1. Extend tmux API in session/tmux/tmux.go with new session/pane commands (session/tmux/tmux.go)
2. Implement platform-specific tmux calls in session/tmux/tmux_unix.go or tmux_windows.go (session/tmux/tmux_unix.go)
3. Update Instance to call new tmux methods during setup in session/instance.go (session/instance.go)
4. Expose feature toggle in config/config.go and allow user configuration (config/config.go)

• Go 1.23+ with Cobra CLI — Fast cross-platform binaries with minimal dependencies; Cobra provides robust CLI argument parsing and daemon support
• Bubble Tea + Charmbracelet libraries — Modern TUI framework with excellent terminal handling; allows rich interactive dashboard without X11/GUI dependencies
• tmux — Proven terminal multiplexer that provides session isolation and PTY management; allows running multiple agents without blocking
• Git worktrees — Native Git feature enabling isolated per-instance working directories; prevents merge conflicts and file lock contention
• go-git library — Pure Go Git implementation; enables programmatic diff generation and worktree operations without shelling to git CLI
• Next.js for web documentation — Static site generation for landing page and docs; decoupled from CLI application, no server runtime required

• Tmux as terminal multiplexer instead of pure PTY management

  • Why: Tmux provides session persistence, automatic cleanup, and cross-platform terminal handling complexities
  • Consequence: Requires tmux installation; adds external dependency but avoids reimplementing terminal emulation logic

• Git worktrees instead of full repository clones per instance

  • Why: Worktrees are lightweight and share object database; faster instance creation and lower disk usage
  • Consequence: Tied to Git; each task requires a Git repo; worktree cleanup must be explicit

• Single-threaded Bubble Tea event loop with blocking Instance operations

  • Why: Simplicity and predictable state management; Bubble Tea is designed for single-threaded TUIs
  • Consequence: Long-running git operations (clone, push)

CRITICAL: Claude Squad requires tmux to be installed and in PATH—it will fail silently without it. The gh CLI must also be available for repository operations. Platform-specific code (daemon_unix.go vs daemon_windows.go) means behavior differs: Unix uses fork/daemonize patterns, Windows uses different process spawning. Configuration is stored in a location printed by cs debug; modifying config files directly can corrupt state (see config/state.go). The --program flag must be a valid, installed CLI tool; typos will cause silent spawn failures. Requires Claude Code / Aider / Codex / Gemini to already be installed—Claude Squad does not bundle them.

• Git Worktrees — Claude Squad isolates each task in a separate git worktree (session/git/worktree.go) so multiple agents can work simultaneously without merge conflicts; understanding this concept is essential to grasp the core value proposition
• Tmux Multiplexing — Claude Squad spawns each agent in a separate tmux session and pane; contributors must understand tmux session/window/pane hierarchy and control sequences to add new multiplexing features
• Bubbletea Event Loop — Claude Squad's TUI uses Charmbracelet's Bubbletea framework with Elm-style message passing (app/app.go); contributors must understand Model/View/Update pattern to modify UI or add new commands
• PTY (Pseudo-Terminal) — Claude Squad uses creack/pty library (session/tmux/pty.go) to manage pseudo-terminal file descriptors for bidirectional communication with spawned agents; essential for capturing interactive output and sending input
• State Machines — Each task instance transitions through states (idle, running, completed, error) managed in app/app.go and session/instance.go; understanding state transitions helps predict behavior and debug hangs
• Daemon Processes — Claude Squad supports background task execution via daemon/daemon.go with platform-specific implementations; contributors must understand Unix fork/exec vs Windows process spawning to add features like task persistence
• Cobra CLI Framework — Claude Squad uses Cobra (cmd/cmd.go) for argument parsing and command routing; contributors adding new top-level commands or flags must extend Cobra command definitions

• anthropics/claude-code — The primary AI agent that Claude Squad manages and orchestrates—understanding its CLI interface is essential for integration
• Aider-AI/aider — Open-source alternative AI agent supported by Claude Squad; users often run Aider instances in parallel with Claude Code
• charmbracelet/bubbletea — Core TUI framework that Claude Squad depends on for interactive terminal rendering and event handling
• go-git/go-git — Provides pure-Go git operations (worktree creation, diff generation) that Claude Squad uses for isolation and change review
• tmux/tmux — External multiplexer that Claude Squad shells out to; understanding tmux session/window/pane model is crucial for debugging

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for session/git package

The git package (session/git/) handles critical operations like worktree management, branching, and diffs, but only has util_test.go. Missing tests for worktree.go, worktree_branch.go, worktree_git.go, and worktree_ops.go leave core git functionality untested. This is high-risk since git operations can corrupt user work.

• [ ] Create session/git/worktree_test.go with tests for worktree creation/deletion operations
• [ ] Create session/git/worktree_branch_test.go covering branch switching and creation logic
• [ ] Create session/git/worktree_git_test.go for git command execution and state tracking
• [ ] Create session/git/worktree_ops_test.go for git operations (commit, push, pull, etc)
• [ ] Ensure tests use mocked git repos to avoid side effects
• [ ] Run 'go test ./session/git' to verify coverage

Add GitHub Actions workflow for cross-platform integration tests

The repo has daemon_unix.go and daemon_windows.go plus tmux_unix.go and tmux_windows.go, indicating platform-specific code paths. Current CI (build.yml, lint.yml) doesn't test on both Windows and Linux. Integration tests for daemon and tmux sessions would catch platform-specific breakages before release.

• [ ] Create .github/workflows/integration-tests.yml that runs on ubuntu-latest and windows-latest matrices
• [ ] Add test targets that exercise daemon/daemon.go, daemon/daemon_unix.go, daemon/daemon_windows.go
• [ ] Add test targets for session/tmux/ package across both platforms
• [ ] Configure workflow to skip tmux tests on Windows (or use conditional steps)
• [ ] Include test output artifacts for debugging failures

Add unit tests for ui/overlay package

The ui/overlay directory contains 4 overlay components (branchPicker, confirmationOverlay, profilePicker, textInput/textOverlay) with no test files. These handle user interactions critical to UX, yet have zero test coverage. Even basic tests for input handling and state changes would improve reliability.

• [ ] Create ui/overlay/branchPicker_test.go with tests for branch selection, filtering, and navigation
• [ ] Create ui/overlay/confirmationOverlay_test.go testing yes/no decision handling
• [ ] Create ui/overlay/profilePicker_test.go testing profile list rendering and selection
• [ ] Create ui/overlay/textInput_test.go testing text input validation and callback execution
• [ ] Use bubbletea's testing patterns (already in ui/terminal_test.go) as reference
• [ ] Verify tests with 'go test ./ui/overlay'

• Add test coverage for session/git/diff.go—currently untested but critical for reviewing changes. Write Go tests that mock git operations and verify diff parsing logic.
• Implement --list flag to display all active instances in non-interactive mode (useful for scripting). Add to cmd/cmd.go, wire through app/app.go, and output instance state in JSON/plain text.
• Add configuration validation in config/config.go—currently no checks that --program binary exists or is executable. Validate on startup and provide helpful error message if agent is not in PATH.

• Medium · Outdated Go Toolchain Version — go.mod. The project specifies Go 1.23.0 with toolchain go1.24.1, but go.mod shows go 1.23.0. This version mismatch and use of Go 1.23.0 (released August 2024) means the codebase may be missing critical security patches. Go 1.24.1 is significantly newer and contains important security fixes for cryptographic operations and standard library vulnerabilities. Fix: Update go.mod to use the latest stable Go version (1.24.1 or later). Review the Go security releases and ensure all dependencies are compatible with the latest version.
• Medium · Transitive Dependency: go-crypto Version — go.mod (indirect dependency). The project depends on github.com/ProtonMail/go-crypto v1.1.5 (indirect dependency via go-git). This version may contain known vulnerabilities in cryptographic operations. Cryptographic libraries require careful version management. Fix: Update go-git to the latest version which may have upgraded go-crypto. Audit the changelog for security-related updates to cryptographic dependencies.
• Medium · PTY/Terminal Input Handling — session/tmux/pty.go, daemon/daemon.go. The project uses github.com/creack/pty for pseudo-terminal operations (session/tmux/pty.go). Direct PTY handling can expose the application to terminal injection attacks if user input is not properly sanitized before being sent to the PTY. Fix: Ensure all user input is properly escaped and validated before being sent to the PTY. Implement input sanitization for shell commands. Review how git operations and user commands are passed to the terminal.
• Medium · Git Operations with Untrusted Input — session/git/worktree_git.go, session/git/worktree_ops.go. The session/git module performs git operations (diff, worktree, branch operations). If branch names, commit messages, or other git parameters come from user input without proper validation, they could be exploited for command injection attacks. Fix: Validate and sanitize all git operation parameters. Use programmatic git APIs (via go-git library) instead of shell command execution where possible. Never pass unsanitized user input to git commands.
• Low · SSH Configuration Handling — go.mod (indirect), config/config.go. The project depends on github.com/kevinburke/ssh_config (indirect dependency). SSH key handling and git operations over SSH could be vulnerable if not properly secured. No evidence of credential storage security in the visible code structure. Fix: Ensure SSH keys are stored securely with proper file permissions (0600). Never log or display SSH keys. Use SSH agent for key management rather than storing keys in the filesystem when possible.
• Low · Clipboard Operations — keys/keys.go (potential), ui/ components. The project uses github.com/atotto/clipboard for clipboard functionality. Sensitive data (like diffs, code snippets, credentials) could be exposed if clipboard contents are logged or not properly managed. Fix: Avoid copying sensitive information to clipboard. If necessary, implement automatic clipboard clearing after a timeout. Never log clipboard contents. Be cautious with API keys and credentials.
• Low · No Visible Secrets Management — config/config.go, keys/keys.go. The project manages multiple AI agents and requires API credentials. No visible secrets management strategy (.env handling, secure credential storage, etc.) is evident in the codebase structure. Fix: Implement proper secrets management using environment variables or secure credential storage. Never hardcode API keys or authentication tokens. Use a secrets management library or system for credential handling.
• Low · No Input Validation Framework — ui/overlay/textInput.go, ui/overlay/profilePicker.go, ui/overlay/branchPicker.go. The UI components (ui/overlay/textInput.go, ui/overlay/textOverlay.go) handle user input for branch names, profiles, and other parameters. No visible comprehensive input validation framework. Fix: Implement strict input validation for all user-provided data. Define whitelists for acceptable characters/patterns. Validate branch names, profile names, and all other user inputs against expected formats.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.