# smtg-ai/claude-squad architecture

> Architecture diagram of the GitHub repository smtg-ai/claude-squad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smtg-ai/claude-squad
- Repository: https://github.com/smtg-ai/claude-squad

## Overview

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/app.go`](https://github.com/smtg-ai/claude-squad/blob/main/app/app.go) (App core), [`ui/terminal.go`](https://github.com/smtg-ai/claude-squad/blob/main/ui/terminal.go) (UI shell), [`session/instance.go`](https://github.com/smtg-ai/claude-squad/blob/main/session/instance.go) (Sessions), [`cmd/cmd.go`](https://github.com/smtg-ai/claude-squad/blob/main/cmd/cmd.go) (Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["CLI runtime"]
  node_main(("main.go<br/>entrypoint<br/>[main.go]"))
  node_cmd["Commands<br/>cli parser<br/>[cmd.go]"]
  node_app["App core<br/>orchestrator<br/>[app.go]"]
  node_config["Config<br/>settings/state<br/>[config.go]"]
  node_state["State store<br/>persisted state<br/>[state.go]"]
  node_log["Logging<br/>[log.go]"]
  node_daemon["Daemon<br/>platform svc<br/>[daemon.go]"]
end

subgraph group_session["Session system"]
  node_session[("Sessions<br/>domain model<br/>[instance.go]")]
  node_storage["Storage<br/>session store<br/>[storage.go]"]
  node_git["Git worktrees<br/>workspace isolation<br/>[worktree.go]"]
  node_tmux["Tmux runtime<br/>terminal isolation<br/>[tmux.go]"]
end

subgraph group_ui["TUI"]
  node_uiroot["UI shell<br/>tui<br/>[terminal.go]"]
  node_overlay["Overlays<br/>modal ui<br/>[overlay.go]"]
  node_list["Session list<br/>view<br/>[list.go]"]
  node_preview["Preview<br/>[preview.go]"]
  node_diff["Diff view<br/>[diff.go]"]
end

subgraph group_web["Public site"]
  node_webapp["Next.js site<br/>marketing/docs<br/>[page.tsx]"]
end

subgraph group_ops["Ops"]
  node_workflow["CI / release<br/>automation<br/>[release.yml]"]
end

node_main -->|"bootstraps"| node_cmd
node_cmd -->|"starts"| node_app
node_app -->|"loads"| node_config
node_app -->|"restores"| node_state
node_app -->|"coordinates"| node_session
node_app -->|"drives"| node_uiroot
node_app -->|"writes"| node_log
node_session -->|"persists"| node_storage
node_session -->|"isolates work"| node_git
node_session -->|"hosts terminals"| node_tmux
node_uiroot -->|"renders"| node_list
node_uiroot -->|"renders"| node_preview
node_uiroot -->|"renders"| node_diff
node_uiroot -->|"opens"| node_overlay
node_overlay -->|"sends intent"| node_app
node_preview -->|"reads"| node_session
node_diff -->|"reads"| node_git
node_cmd -.->|"platform hooks"| node_daemon
node_app -.->|"separate site"| node_webapp
node_workflow -.->|"builds"| node_main
node_workflow -.->|"deploys"| node_webapp

click node_main "https://github.com/smtg-ai/claude-squad/blob/main/main.go"
click node_cmd "https://github.com/smtg-ai/claude-squad/blob/main/cmd/cmd.go"
click node_app "https://github.com/smtg-ai/claude-squad/blob/main/app/app.go"
click node_config "https://github.com/smtg-ai/claude-squad/blob/main/config/config.go"
click node_state "https://github.com/smtg-ai/claude-squad/blob/main/config/state.go"
click node_log "https://github.com/smtg-ai/claude-squad/blob/main/log/log.go"
click node_daemon "https://github.com/smtg-ai/claude-squad/blob/main/daemon/daemon.go"
click node_session "https://github.com/smtg-ai/claude-squad/blob/main/session/instance.go"
click node_storage "https://github.com/smtg-ai/claude-squad/blob/main/session/storage.go"
click node_git "https://github.com/smtg-ai/claude-squad/blob/main/session/git/worktree.go"
click node_tmux "https://github.com/smtg-ai/claude-squad/blob/main/session/tmux/tmux.go"
click node_uiroot "https://github.com/smtg-ai/claude-squad/blob/main/ui/terminal.go"
click node_overlay "https://github.com/smtg-ai/claude-squad/blob/main/ui/overlay/overlay.go"
click node_list "https://github.com/smtg-ai/claude-squad/blob/main/ui/list.go"
click node_preview "https://github.com/smtg-ai/claude-squad/blob/main/ui/preview.go"
click node_diff "https://github.com/smtg-ai/claude-squad/blob/main/ui/diff.go"
click node_webapp "https://github.com/smtg-ai/claude-squad/blob/main/web/src/app/page.tsx"
click node_workflow "https://github.com/smtg-ai/claude-squad/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cmd,node_app,node_config,node_state,node_log,node_daemon toneBlue
class node_session,node_storage,node_git,node_tmux toneAmber
class node_uiroot,node_overlay,node_list,node_preview,node_diff toneMint
class node_webapp toneRose
class node_workflow toneIndigo
```

## Components

### CLI runtime

Go binary entrypoint, command parsing, orchestration, and support subsystems.

- [main.go](https://github.com/smtg-ai/claude-squad/blob/main/main.go): entrypoint · Binary entrypoint that hands control to the command layer. · `main.go`
- [Commands](https://github.com/smtg-ai/claude-squad/blob/main/cmd/cmd.go): cli parser · Cobra-style CLI surface for flags, subcommands, and shell completion. · `cmd/cmd.go`
- [App core](https://github.com/smtg-ai/claude-squad/blob/main/app/app.go): orchestrator · Top-level interactive controller coordinating config, sessions, and UI actions. · `app/app.go`
- [Config](https://github.com/smtg-ai/claude-squad/blob/main/config/config.go): settings/state · User profiles, launch commands, and persisted application state. · `config/config.go`
- [State store](https://github.com/smtg-ai/claude-squad/blob/main/config/state.go): persisted state · Runtime/session state persisted separately from static config. · `config/state.go`
- [Logging](https://github.com/smtg-ai/claude-squad/blob/main/log/log.go): logging · Centralized application logging. · `log/log.go`
- [Daemon](https://github.com/smtg-ai/claude-squad/blob/main/daemon/daemon.go): platform svc · Platform-specific background/session support code. · `daemon/daemon.go`

### Session system

Task sessions, workspace isolation, and terminal/session management.

- [Sessions](https://github.com/smtg-ai/claude-squad/blob/main/session/instance.go): domain model · Managed task/session lifecycle and storage boundary. · `session/instance.go`
- [Storage](https://github.com/smtg-ai/claude-squad/blob/main/session/storage.go): session store · Persistence for session metadata and lifecycle records. · `session/storage.go`
- [Git worktrees](https://github.com/smtg-ai/claude-squad/blob/main/session/git/worktree.go): workspace isolation · Worktree, branch, and diff management for isolated task workspaces. · `session/git/worktree.go`
- [Tmux runtime](https://github.com/smtg-ai/claude-squad/blob/main/session/tmux/tmux.go): terminal isolation · Tmux and PTY management for attach/detach and concurrent sessions. · `session/tmux/tmux.go`

### TUI

Interactive terminal interface and overlays.

- [UI shell](https://github.com/smtg-ai/claude-squad/blob/main/ui/terminal.go): tui · Session list, preview, diff, tabs, menus, and terminal rendering. · `ui/terminal.go`
- [Overlays](https://github.com/smtg-ai/claude-squad/blob/main/ui/overlay/overlay.go): modal ui · Branch/profile pickers, confirmations, and text-entry overlays. · `ui/overlay/overlay.go`
- [Session list](https://github.com/smtg-ai/claude-squad/blob/main/ui/list.go): view · Primary browser for managed sessions. · `ui/list.go`
- [Preview](https://github.com/smtg-ai/claude-squad/blob/main/ui/preview.go): view · Read-only session and diff preview pane. · `ui/preview.go`
- [Diff view](https://github.com/smtg-ai/claude-squad/blob/main/ui/diff.go): view · Code change rendering and comparison surface. · `ui/diff.go`

### Public site

Separate Next.js documentation and landing site.

- [Next.js site](https://github.com/smtg-ai/claude-squad/blob/main/web/src/app/page.tsx): marketing/docs · Separate public website for docs and landing page content. · `web/src/app/page.tsx`

### Ops

Release and CI automation.

- [CI / release](https://github.com/smtg-ai/claude-squad/blob/main/.github/workflows/release.yml): automation · Build, lint, deploy, and release pipelines for the project. · `.github/workflows/release.yml`

## Connections

- 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.
