# scottdsnr/tmux-workspace-manager architecture

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

- Interactive diagram: https://gitdiagram.com/scottdsnr/tmux-workspace-manager
- Repository: https://github.com/scottdsnr/tmux-workspace-manager

## Overview

tmux-workspace is a YAML-driven CLI and interactive manager for defining, validating, editing, and starting or stopping tmux workspaces. The main workflow selects a profile, resolves its workspace/window/pane configuration, creates tmux windows and panes with commands and inherited environment, then attaches; stopping signals panes, runs teardown commands, and kills the session. The README also documents settings, legacy migration, and self-update. Some implementation excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`cmd/twm/main.go`](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/main.go) (Command router), [`cmd/twm/workspace.go`](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/workspace.go) (Workspace lifecycle), [`cmd/twm/config.go`](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/config.go) (Profile configuration), [`cmd/twm/tui_app.go`](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_app.go) (TUI controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and TUI"]
  node_main["Command router<br/>[main.go]"]
  node_dashboard["Workspace dashboard<br/>[tui_dashboard.go]"]
  node_tui["TUI controller<br/>[tui_app.go]"]
  node_progress["Progress and confirmation<br/>[tui_progress.go]"]
end

subgraph group_profiles["Profiles and settings"]
  node_wizard["Profile wizard<br/>[tui_wizard.go]"]
  node_profile_editor["Profile editing<br/>[wizard.go]"]
  node_config["Profile configuration<br/>[config.go]"]
  node_settings_ui["Settings form<br/>[tui_settings.go]"]
  node_settings["Settings management<br/>[settings.go]"]
  node_validate["Profile validation<br/>[config.go]"]
end

subgraph group_sessions["Session lifecycle"]
  node_workspace["Workspace lifecycle<br/>[workspace.go]"]
  node_tmux["tmux command adapter<br/>[tmux.go]"]
end

subgraph group_maintenance["Maintenance"]
  node_migration["Legacy migration<br/>[upgrade.go]"]
  node_updater["Self updater<br/>[update.go]"]
end

node_user(("Terminal user"))
node_tmux_service["tmux server"]
node_editor["External editor"]
node_github["GitHub releases"]

node_user -->|"runs commands"| node_main
node_main -->|"opens dashboard"| node_dashboard
node_main -->|"starts or stops"| node_workspace
node_main -->|"creates profile"| node_wizard
node_main -->|"edits or lists"| node_profile_editor
node_main -->|"validates profile"| node_validate
node_main -->|"opens settings"| node_settings_ui
node_main -->|"edits settings"| node_settings
node_main -->|"runs migration"| node_migration
node_main -->|"checks update"| node_updater
node_dashboard -->|"loads summaries"| node_profile_editor
node_dashboard -->|"requests screens"| node_tui
node_tui -->|"hosts wizard"| node_wizard
node_tui -->|"hosts form"| node_settings_ui
node_tui -->|"shows operation progress"| node_progress
node_wizard -->|"saves profile"| node_config
node_profile_editor -->|"loads and saves"| node_config
node_validate -->|"reads profile"| node_config
node_settings_ui -->|"saves preferences"| node_settings
node_workspace -->|"loads profile"| node_config
node_workspace -->|"reads preferences"| node_settings
node_workspace -->|"builds and tears down"| node_tmux
node_tmux -->|"creates panes and sessions"| node_tmux_service
node_workspace -.->|"opens raw profile"| node_editor
node_migration -->|"merges profiles"| node_config
node_updater -->|"checks and downloads"| node_github

click node_main "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/main.go"
click node_dashboard "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_dashboard.go"
click node_tui "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_app.go"
click node_progress "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_progress.go"
click node_wizard "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_wizard.go"
click node_profile_editor "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/wizard.go"
click node_config "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/config.go"
click node_settings_ui "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_settings.go"
click node_settings "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/settings.go"
click node_validate "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/config.go"
click node_workspace "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/workspace.go"
click node_tmux "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tmux.go"
click node_migration "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/upgrade.go"
click node_updater "https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/update.go"

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_dashboard,node_tui,node_progress,node_user toneBlue
class node_wizard,node_profile_editor,node_config,node_settings_ui,node_settings,node_validate toneAmber
class node_workspace,node_tmux,node_tmux_service toneMint
class node_migration,node_updater toneRose
class node_editor,node_github toneIndigo
```

## Components

### CLI and TUI

- [Command router](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/main.go): `cmd/twm/main.go`
- [Workspace dashboard](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_dashboard.go): `cmd/twm/tui_dashboard.go`
- [TUI controller](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_app.go): `cmd/twm/tui_app.go`
- [Progress and confirmation](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_progress.go): `cmd/twm/tui_progress.go`

### Profiles and settings

- [Profile wizard](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_wizard.go): `cmd/twm/tui_wizard.go`
- [Profile editing](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/wizard.go): `cmd/twm/wizard.go`
- [Profile configuration](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/config.go): `cmd/twm/config.go`
- [Settings form](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tui_settings.go): `cmd/twm/tui_settings.go`
- [Settings management](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/settings.go): `cmd/twm/settings.go`
- [Profile validation](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/config.go): `cmd/twm/config.go`

### Session lifecycle

- [Workspace lifecycle](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/workspace.go): `cmd/twm/workspace.go`
- [tmux command adapter](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/tmux.go): `cmd/twm/tmux.go`

### Maintenance

- [Legacy migration](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/upgrade.go): `cmd/twm/upgrade.go`
- [Self updater](https://github.com/scottdsnr/tmux-workspace-manager/blob/master/cmd/twm/update.go): `cmd/twm/update.go`

### Other components

- **Terminal user**
- **tmux server**
- **External editor**
- **GitHub releases**

## Connections

- Terminal user → Command router: runs commands
- Command router → Workspace dashboard: opens dashboard
- Command router → Workspace lifecycle: starts or stops
- Command router → Profile wizard: creates profile
- Command router → Profile editing: edits or lists
- Command router → Profile validation: validates profile
- Command router → Settings form: opens settings
- Command router → Settings management: edits settings
- Command router → Legacy migration: runs migration
- Command router → Self updater: checks update
- Workspace dashboard → Profile editing: loads summaries
- Workspace dashboard → TUI controller: requests screens
- TUI controller → Profile wizard: hosts wizard
- TUI controller → Settings form: hosts form
- TUI controller → Progress and confirmation: shows operation progress
- Profile wizard → Profile configuration: saves profile
- Profile editing → Profile configuration: loads and saves
- Profile validation → Profile configuration: reads profile
- Settings form → Settings management: saves preferences
- Workspace lifecycle → Profile configuration: loads profile
- Workspace lifecycle → Settings management: reads preferences
- Workspace lifecycle → tmux command adapter: builds and tears down
- tmux command adapter → tmux server: creates panes and sessions
- Workspace lifecycle → External editor: opens raw profile
- Legacy migration → Profile configuration: merges profiles
- Self updater → GitHub releases: checks and downloads