smtg-ai/claude-squad
Summary
Claude Squad is a terminal multiplexer for AI coding agents (Claude Code, Codex, Gemini, Aider) that runs each agent in an isolated tmux session backed by a git worktree, so multiple tasks can run simultaneously without branch conflicts. You get a Bubbletea TUI to manage, preview, diff, pause/resume, and auto-accept prompts across all running agents. Think of it as a session manager specifically designed for the 'let AI work in the background while I do other things' workflow.
Great for
Great for people interested in building terminal UIs around AI agent orchestration, specifically the intersection of tmux session management, git worktree isolation, and multi-agent workflow automation
Easy wins
- +Add 'good first issue' / 'help wanted' labels to the 40 open issues — the maintainer hasn't triaged them at all, so browsing and categorizing is low-hanging fruit
- +The statusMonitor.hash() in session/tmux/tmux.go has a commented TODO: 'this allocation sucks since the string is probably large' — optimizing to hash bytes directly without string conversion is a well-scoped performance fix
- +Windows support stubs exist (daemon_windows.go, tmux_windows.go) but tmux doesn't run natively on Windows — documenting WSL2 requirements or adding a startup error with clear instructions would prevent a common user confusion
- +The profile picker (ui/overlay/profilePicker.go) and branch picker (ui/overlay/branchPicker.go) are separate overlays with likely duplicated nav logic — consolidating them into a generic picker component would be a meaningful refactor with clear scope
Red flags
- !Two nearly identical async-start message types exist: instanceStartDoneMsg and instanceStartedMsg in app.go both handle the same scenario (instance finished starting) with slightly different logic — this looks like a refactor left half-finished and could cause subtle bugs if both fire
- !The Detach() method in session/tmux/tmux.go explicitly panics on PTY close failure: 'It's better to just panic and have the user re-invoke the program' — this is a known design choice but is a hard crash in a TUI tool that could corrupt terminal state
- !commit_count and contributor_count in the repo metadata both show 1, which contradicts the README's CI badges and 14 listed contributors — the metadata collection seems broken, so actual project health is hard to assess from stats alone
- !The stdin-nuking heuristic in tmux.go Attach() ('nuke the first bytes of stdin, up to 64, to prevent tmux from reading control sequences') is a timing-based hack (50ms window) that could silently swallow real user input on slow systems
Code quality
Error handling is consistently done with wrapped fmt.Errorf throughout — session/instance.go properly collects multiple cleanup errors and combines them rather than dropping them. The dependency injection pattern in tmux.go (NewTmuxSessionWithDeps for testing vs NewTmuxSession for prod) shows deliberate testability thinking. The main weakness is app/app.go: it's a sprawling 800+ line god struct mixing UI state, business logic, and persistence — the instanceStartDoneMsg vs instanceStartedMsg handling suggests the async instance-start flow was refactored mid-stream and left two partially overlapping code paths (both handle promptAfterName and call storage.SaveInstances).
What makes it unique
This isn't just another Claude wrapper — the git worktree isolation per agent is the genuinely interesting architectural decision, solving a real problem (branch conflicts when running multiple AI agents). The combination of tmux + worktrees + TUI in one Go binary is a specific and useful niche. The closest comparable tool would be manually managing tmux sessions + git worktrees yourself, which this actually automates well. The 6.7k stars suggest it found product-market fit quickly in the 'agentic coding workflow' space.