How smtg-ai/claude-squad works
1. Repository shape
This is primarily a Go CLI/TUI application named claude-squad (cs) for managing multiple AI-agent sessions. The core runtime is the Go code under app, cmd, config, session, ui, daemon, log, and main.go. The web/ directory is a separate Next.js site used for the public docs/landing page, not the CLI runtime.
2. Process entry and command layer
main.go is the binary entrypoint and hands off to cmd/, which appears to use Cobra-style command parsing. This layer exposes the CLI surface shown in the README: startup flags (--autoyes, --program) plus subcommands like debug, reset, version, and shell completion. It is the boundary between shell invocation and the application orchestrator.
3. Application orchestration
app/ is the top-level controller for interactive mode. It coordinates configuration, session discovery, UI state, and user actions. In architectural terms, it sits between the command layer and the lower-level session backends, turning keypresses and menu actions into session lifecycle operations.
4. Persistent configuration and state
config/ handles user configuration and stored state, including the JSON config path described in the README (~/.claude-squad/config.json). The config supports named profiles, a default program, and launch commands for different assistants. state.go suggests there is separate persisted runtime state for sessions/instances, so the app can resume or redisplay sessions across restarts.
5. Session model and storage
session/ is the core domain layer for an “instance” or task session. session/storage.go likely persists session metadata, while session/instance.go models the unit the UI manages. This is the main boundary for lifecycle events: create, attach, detach, kill, resume, checkout, and sync.
6. Git workspace isolation
session/git/ encapsulates git worktree behavior. The repository’s architecture is built around isolating each task in its own worktree/branch, and this package owns that responsibility: creating worktrees, deriving branches, computing diffs, and handling git operations related to checkouts and branch management. This is the main data boundary for code changes, since each agent works in a separate filesystem workspace.
7. Terminal session isolation
session/tmux/ encapsulates tmux and PTY management. Each agent runs inside its own tmux-backed terminal session, which is what enables background execution, detach/reattach, and multiple concurrent tasks inside one terminal app. The OS-specific files (tmux_unix.go, tmux_windows.go, daemon_unix.go, daemon_windows.go) show the app adapts its process/session handling by platform.
8. Interactive TUI
ui/ contains the terminal user interface: session list, preview pane, diff view, tabbed window management, menu bar, terminal rendering, and error handling. The ui/overlay/ subpackage adds modal interactions such as branch/profile pickers, confirmations, and text input. The UI is read-heavy: it renders session state and diffs, and sends user intent back to app/ for execution.
9. User action flow
The main runtime flow is: user starts cs → config/state are loaded → existing sessions are listed → the UI renders a session list plus preview/diff panes → key commands trigger operations in app/ → session/git mutates worktrees/branches and session/tmux mutates terminal sessions. This keeps presentation, orchestration, and system-level side effects separated.
10. Launchable agents and profiles
Agent programs are not hardcoded to one tool. The config/profile system lets the app launch claude, codex, gemini, aider, or any shell command configured by the user. That means the repository’s core abstraction is “managed task session,” not a specific assistant implementation.
11. Logging and operational support
log/ centralizes application logging, while daemon/ and keys/ are supporting subsystems for runtime behavior and interaction details. Together with the CI/release workflows and GoReleaser config, they indicate the project is packaged as a cross-platform CLI binary with release automation rather than a long-running server.
12. External dependencies that matter architecturally
The app depends on tmux for session isolation and on git worktrees for filesystem isolation; the README also calls out gh as a prerequisite, which matters for GitHub-oriented workflows. These external tools are part of the architecture, because the CLI is essentially a coordinator around them rather than a self-contained process manager.
Main entry points: app.go App core · terminal.go UI shell · instance.go Sessions · cmd.go Commands
Components 18
CLI runtime
Go binary entrypoint, command parsing, orchestration, and support subsystems.
- main.go · Binary entrypoint that hands control to the command layer.
main.go - Commands · Cobra-style CLI surface for flags, subcommands, and shell completion.
cmd/cmd.go - App core · Top-level interactive controller coordinating config, sessions, and UI actions.
app/app.go - Config · User profiles, launch commands, and persisted application state.
config/config.go - State store · Runtime/session state persisted separately from static config.
config/state.go - Logging · Centralized application logging.
log/log.go - Daemon · Platform-specific background/session support code.
daemon/daemon.go
Session system
Task sessions, workspace isolation, and terminal/session management.
- Sessions · Managed task/session lifecycle and storage boundary.
session/instance.go - Storage · Persistence for session metadata and lifecycle records.
session/storage.go - Git worktrees · Worktree, branch, and diff management for isolated task workspaces.
session/git/worktree.go - Tmux runtime · Tmux and PTY management for attach/detach and concurrent sessions.
session/tmux/tmux.go
TUI
Interactive terminal interface and overlays.
- UI shell · Session list, preview, diff, tabs, menus, and terminal rendering.
ui/terminal.go - Overlays · Branch/profile pickers, confirmations, and text-entry overlays.
ui/overlay/overlay.go - Session list · Primary browser for managed sessions.
ui/list.go - Preview · Read-only session and diff preview pane.
ui/preview.go - Diff view · Code change rendering and comparison surface.
ui/diff.go
Public site
Separate Next.js documentation and landing site.
- Next.js site · Separate public website for docs and landing page content.
web/src/app/page.tsx
Ops
Release and CI automation.
- CI / release · Build, lint, deploy, and release pipelines for the project.
.github/workflows/release.yml
Connections 21
- main.go → Commands: bootstraps · Binary entrypoint hands execution to CLI parsing.
- Commands → App core: starts · Subcommands and flags invoke the application controller.
- App core → Config: loads · Reads profiles, launch commands, and persistent settings.
- App core → State store: restores · Restores runtime/session state for resume and redisplay.
- App core → Sessions: coordinates · Creates, attaches, resumes, kills, and syncs sessions.
- App core → UI shell: drives · Feeds user actions and renders application state.
- App core → Logging: writes · Emits operational and error logging.
- Sessions → Storage: persists · Stores session metadata and lifecycle state.
- Sessions → Git worktrees: isolates work · Uses worktrees and branches for task-specific workspaces.
- Sessions → Tmux runtime: hosts terminals · Runs agent processes in tmux/PTTY-backed sessions.
- UI shell → Session list: renders · Main session browser view.
- UI shell → Preview: renders · Preview pane for selected session output and metadata.
- UI shell → Diff view: renders · Diff pane for workspace changes.
- UI shell → Overlays: opens · Shows modal interactions and input overlays.
- Overlays → App core: sends intent · User selections and confirmations are returned to orchestration.
- Preview → Sessions: reads · Displays session state and status.
- Diff view → Git worktrees: reads · Renders repository changes from worktree state.
- Commands → Daemon: platform hooks · Command/runtime path reaches platform-specific support when needed.
- App core → Next.js site: separate site · Public website is adjacent to, but separate from, the CLI runtime.
- CI / release → main.go: builds · CI/release pipeline produces the Go binary.
- CI / release → Next.js site: deploys · Site workflows build and publish the Next.js frontend.