# supabitapp/supacode architecture

> Architecture diagram of the GitHub repository supabitapp/supacode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/supabitapp/supacode
- Repository: https://github.com/supabitapp/supacode

## Overview

1. **Overall shape**
   - Supacode is a macOS native “command center” for coding-agent workflows.
   - The repository is split into a GUI app, a companion CLI, and a shared core library. The architecture is strongly modular and feature-oriented, with The Composable Architecture as the main state-management pattern.

2. **Top-level build and packaging**
   - The project is assembled with Tuist rather than a hand-maintained Xcode project.
   - Build orchestration lives in `Makefile`, `Tuist.swift`, `Workspace.swift`, and several shell scripts.
   - The repo also vendors or builds external native dependencies, especially `libghostty`-based terminal support and `zmx`.

3. **Core shared layer**
   - `SupacodeSettingsShared` contains logic reused across the app and settings-related surfaces.
   - This layer holds:
     - shared models and domain types,
     - persistence keys and file formats,
     - installers for agent/editor settings files,
     - shared clients for shell, notifications, analytics, settings, and agent integrations.
   - This is the main boundary separating “portable logic” from UI-specific code.

4. **macOS app shell**
   - `supacode` is the primary GUI application.
   - Its `App` layer wires together window lifecycle, crash reporting, telemetry, deep links, keyboard handling, and window behavior.
   - `ContentView` and the feature tree below it drive the main UI, while `supacodeApp.swift` is the entry point.
   - The app depends on a large set of domain, client, feature, and infrastructure modules.

5. **Feature-driven UI architecture**
   - Most user-facing behavior is organized under `supacode/Features`.
   - Major feature areas are:
     - **Repositories**: sidebar, worktree selection, worktree creation, branch/grouping, notifications, PR status, repo customization.
     - **Terminal**: tabs, split layout, embedded terminal surfaces, persistence of layouts, search overlays, notification routing.
     - **Settings**: global settings, GitHub, keyboard shortcuts, developer/update settings.
     - **Command Palette** and **App** coordination.
     - **Agent Presence**: live coding-agent status and avatars.
     - **Updates**: app update state and flows.
   - Each feature typically has its own reducer, model types, and views, which is the main interaction pattern for the UI.

6. **Repository and worktree management**
   - Repository state is a central product concept: sidebar structure, branches, worktrees, archived worktrees, and customization all live here.
   - `supacode/Domain` defines the core repository/worktree concepts such as `Repository`, `Worktree`, `PendingWorktree`, `SplitDirection`, and loading/progress state.
   - The repository feature layer uses watchers and persistence to keep the UI synchronized with Git state and worktree state over time.
   - There is clear separation between:
     - Git/repo discovery,
     - persisted sidebar and customization state,
     - and rendered sidebar/worktree views.

7. **Terminal subsystem**
   - The terminal area is not a generic shell view; it is a managed surface system built around Ghostty.
   - `supacode/Infrastructure/Ghostty` adapts Ghostty runtime, commands, shortcuts, split actions, and surface bridging into the app.
   - `supacode/Features/Terminal` manages:
     - tab identity and tab state,
     - split-tree layout,
     - persistence of terminal layouts,
     - worktree-to-terminal mapping,
     - terminal notifications and progress indicators.
   - Data flows here are: app/feature state → Ghostty bridge/runtime → embedded terminal surface → terminal/tab state updates back into reducers.

8. **Agent and coding-assistant integration**
   - A major architecture theme is integration with multiple coding agents and their hooks/settings:
     - Claude,
     - Codex,
     - Kiro,
     - Pi.
   - Shared business logic under `SupacodeSettingsShared/BusinessLogic` installs hook settings, CLI skills/extensions, and agent-specific payload formats.
   - `AgentHookSocketServer` and related socket/payload types indicate local IPC used to observe agent activity and feed it into the app.
   - `Features/AgentPresence` turns that backend signal into UI state, badges, avatars, and sidebar cards.

9. **Settings and persistence**
   - Global and repository-local settings are modeled separately.
   - Persistence helpers cover:
     - app settings,
     - repository settings,
     - sidebar state,
     - terminal layouts,
     - archived worktree dates,
     - and related migration logic.
   - This repository treats file-based persistence and installer-style side effects as first-class architecture, not incidental utilities.

10. **CLI companion**
   - `supacode-cli` is a separate command-line entry point.
   - It exposes commands for opening, querying repositories, settings, sockets, surfaces, tabs, worktrees, and worktree scripts.
   - The CLI has a transport layer with dispatcher, query dispatcher, socket client, and socket discovery, suggesting local IPC with a running Supacode app instance.
   - In diagram terms, the CLI is a control plane that can address the app and/or local repo state without going through the GUI.

11. **External integrations**
   - Git is a core dependency, used for repository discovery, worktree management, references, and branch/PR context.
   - GitHub integration is implemented both through a CLI client and structured API models, including pull request, workflow run, merge queue, and repo view responses.
   - Notification delivery is handled through system notification clients and sound assets.
   - Updates are integrated through a dedicated updater client and update feature.
   - These are all application-level integrations rather than background services hosted in the repo.

12. **Infrastructure and tooling boundaries**
   - `supacode/Infrastructure` contains low-level app runtime adapters, especially for Ghostty and window/surface behavior.
   - `supacode/Support` and `SupacodeSettingsShared/Support` hold logging, path conventions, and small cross-cutting UI helpers.
   - Tests are extensive and mirror the architecture: reducer tests, persistence tests, Git/GitHub tests, Ghostty surface tests, and agent-hook tests.
   - The repo’s architecture is therefore best drawn as:
     - GUI app and CLI as two entry points,
     - shared business/domain layer underneath,
     - feature modules as the main state/UI units,
     - infrastructure adapters at the edge,
     - and Git/GitHub/agent/terminal integrations as external systems.

Main entry points: [`supacode/Features/App/Reducer/AppFeature.swift`](https://github.com/supabitapp/supacode/blob/main/supacode/Features/App/Reducer/AppFeature.swift) (App reducer), [`supacode/Features/Repositories/Reducer/RepositoriesFeature.swift`](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift) (Repositories), [`supacode/Features/Terminal/Reducer/TerminalsFeature.swift`](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Terminal/Reducer/TerminalsFeature.swift) (Terminal), [`SupacodeSettingsShared`](https://github.com/supabitapp/supacode/tree/main/SupacodeSettingsShared) (Shared core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_tooling["Tooling"]
  node_node_build["Build setup<br/>tuist/packaging<br/>[Tuist.swift]"]
  node_node_vendored[("Native deps<br/>vendored/native")]
end

subgraph group_group_shared["Shared core"]
  node_node_settings_shared["Shared core<br/>shared library"]
  node_node_domain["Repo domain<br/>domain models"]
end

subgraph group_group_app["GUI app"]
  node_node_app_shell["App shell<br/>macOS app<br/>[supacodeApp.swift]"]
  node_node_content["Content view<br/>root UI<br/>[ContentView.swift]"]
end

subgraph group_group_features["UI features"]
  node_node_app_feature["App reducer<br/>tca feature<br/>[AppFeature.swift]"]
  node_node_repositories["Repositories<br/>tca feature"]
  node_node_repo_sidebar["Sidebar state<br/>repo ui logic"]
  node_node_terminal["Terminal<br/>tca feature"]
  node_node_terminal_models["Tab layout<br/>terminal models<br/>[SplitTree.swift]"]
  node_node_settings_feature["Settings<br/>tca feature<br/>[SettingsView.swift]"]
  node_node_agent_presence["Agent presence<br/>tca feature"]
  node_node_updates["Updates<br/>tca feature"]
end

subgraph group_group_infra["Infrastructure"]
  node_node_ghostty_infra["Ghostty bridge<br/>runtime adapter"]
  node_node_agent_socket["Agent socket<br/>local ipc"]
end

subgraph group_group_cli["CLI"]
  node_node_cli["CLI entry<br/>command-line<br/>[SupacodeCLI.swift]"]
  node_node_cli_transport["CLI transport<br/>ipc client<br/>[Dispatcher.swift]"]
end

subgraph group_group_external["External systems"]
  node_node_git[("Git<br/>external vcs")]
  node_node_github[("GitHub<br/>external api")]
  node_node_agents[("Coding agents<br/>external integrations")]
end

node_node_build -->|"builds"| node_node_app_shell
node_node_build -->|"builds"| node_node_cli
node_node_build -->|"vendors"| node_node_vendored
node_node_app_shell -->|"hosts"| node_node_content
node_node_content -->|"drives"| node_node_app_feature
node_node_app_feature -->|"coordinates"| node_node_repositories
node_node_app_feature -->|"coordinates"| node_node_terminal
node_node_app_feature -->|"opens"| node_node_settings_feature
node_node_app_feature -->|"surfaces"| node_node_agent_presence
node_node_repositories -->|"uses"| node_node_repo_sidebar
node_node_repositories -->|"models"| node_node_domain
node_node_repositories -->|"reads"| node_node_git
node_node_repositories -->|"shows"| node_node_github
node_node_terminal -->|"organizes"| node_node_terminal_models
node_node_terminal -->|"bridges"| node_node_ghostty_infra
node_node_terminal -->|"maps"| node_node_domain
node_node_terminal -->|"binds"| node_node_git
node_node_settings_feature -->|"shares"| node_node_settings_shared
node_node_settings_shared -->|"installs"| node_node_agents
node_node_settings_shared -->|"queries"| node_node_git
node_node_agent_presence -->|"listens"| node_node_agent_socket
node_node_agent_socket -->|"observes"| node_node_agents
node_node_cli -->|"dispatches"| node_node_cli_transport
node_node_cli_transport -->|"targets"| node_node_app_shell
node_node_cli_transport -->|"queries"| node_node_git
node_node_github -->|"augments"| node_node_git
node_node_updates -->|"integrates"| node_node_app_shell
node_node_settings_shared -->|"extends"| node_node_domain

click node_node_build "https://github.com/supabitapp/supacode/blob/main/Tuist.swift"
click node_node_vendored "https://github.com/supabitapp/supacode/tree/main/ThirdParty/ghostty"
click node_node_settings_shared "https://github.com/supabitapp/supacode/tree/main/SupacodeSettingsShared"
click node_node_domain "https://github.com/supabitapp/supacode/tree/main/supacode/Domain"
click node_node_app_shell "https://github.com/supabitapp/supacode/blob/main/supacode/App/supacodeApp.swift"
click node_node_content "https://github.com/supabitapp/supacode/blob/main/supacode/App/ContentView.swift"
click node_node_app_feature "https://github.com/supabitapp/supacode/blob/main/supacode/Features/App/Reducer/AppFeature.swift"
click node_node_repositories "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift"
click node_node_repo_sidebar "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift"
click node_node_terminal "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Terminal/Reducer/TerminalsFeature.swift"
click node_node_terminal_models "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Terminal/Models/SplitTree.swift"
click node_node_settings_feature "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Settings/Views/SettingsView.swift"
click node_node_agent_presence "https://github.com/supabitapp/supacode/blob/main/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift"
click node_node_updates "https://github.com/supabitapp/supacode/blob/main/supacode/Features/Updates/Reducer/UpdatesFeature.swift"
click node_node_ghostty_infra "https://github.com/supabitapp/supacode/blob/main/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift"
click node_node_agent_socket "https://github.com/supabitapp/supacode/blob/main/supacode/Infrastructure/AgentHookSocketServer.swift"
click node_node_cli "https://github.com/supabitapp/supacode/blob/main/supacode-cli/SupacodeCLI.swift"
click node_node_cli_transport "https://github.com/supabitapp/supacode/blob/main/supacode-cli/Transport/Dispatcher.swift"
click node_node_github "https://github.com/supabitapp/supacode/blob/main/supacode/Clients/Github/GithubIntegrationClient.swift"
click node_node_agents "https://github.com/supabitapp/supacode/blob/main/SupacodeSettingsShared/BusinessLogic/AgentIntegration.swift"

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_node_build,node_node_vendored,node_node_git,node_node_github,node_node_agents toneBlue
class node_node_settings_shared,node_node_domain toneAmber
class node_node_app_shell,node_node_content toneMint
class node_node_app_feature,node_node_repositories,node_node_repo_sidebar,node_node_terminal,node_node_terminal_models,node_node_settings_feature,node_node_agent_presence,node_node_updates toneRose
class node_node_ghostty_infra,node_node_agent_socket toneIndigo
class node_node_cli,node_node_cli_transport toneTeal
```

## Components

### Tooling

Build, workspace, scripts, and vendored dependencies.

- [Build setup](https://github.com/supabitapp/supacode/blob/main/Tuist.swift): tuist/packaging · Repo assembly and build orchestration via Tuist, Makefile, workspace, and scripts. · `Tuist.swift`
- [Native deps](https://github.com/supabitapp/supacode/tree/main/ThirdParty/ghostty): vendored/native · Third-party native runtime dependencies and patches, including Ghostty and zmx. · `ThirdParty/ghostty`

### Shared core

Portable domain, persistence, clients, and agent-installation logic reused by app surfaces.

- [Shared core](https://github.com/supabitapp/supacode/tree/main/SupacodeSettingsShared): shared library · Cross-surface settings logic, models, persistence keys, installers, and shared clients. · `SupacodeSettingsShared`
- [Repo domain](https://github.com/supabitapp/supacode/tree/main/supacode/Domain): domain models · Core repository, worktree, split-direction, and loading/progress types. · `supacode/Domain`

### GUI app

macOS application shell and top-level orchestration.

- [App shell](https://github.com/supabitapp/supacode/blob/main/supacode/App/supacodeApp.swift): macOS app · Main app entry, window lifecycle, telemetry, crash reporting, deeplinks, and command handling. · `supacode/App/supacodeApp.swift`
- [Content view](https://github.com/supabitapp/supacode/blob/main/supacode/App/ContentView.swift): root UI · Top-level view composition that drives the main app experience. · `supacode/App/ContentView.swift`

### UI features

Feature reducers and views organized by product area.

- [App reducer](https://github.com/supabitapp/supacode/blob/main/supacode/Features/App/Reducer/AppFeature.swift): tca feature · App coordination feature for deeplinks, command palette, opening worktrees, and global flow. · `supacode/Features/App/Reducer/AppFeature.swift`
- [Repositories](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Repositories/Reducer/RepositoriesFeature.swift): tca feature · Sidebar, worktrees, branch grouping, repo customization, notifications, and PR status. · `supacode/Features/Repositories/Reducer/RepositoriesFeature.swift`
- [Sidebar state](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift): repo ui logic · Sidebar structure, persistence, grouping, migration, and watcher coordination. · `supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift`
- [Terminal](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Terminal/Reducer/TerminalsFeature.swift): tca feature · Terminal tabs, split-tree layout, worktree-terminal mapping, persistence, and notifications. · `supacode/Features/Terminal/Reducer/TerminalsFeature.swift`
- [Tab layout](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Terminal/Models/SplitTree.swift): terminal models · Terminal tab identity, split tree, layout snapshots, and worktree surface state. · `supacode/Features/Terminal/Models/SplitTree.swift`
- [Settings](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Settings/Views/SettingsView.swift): tca feature · Global and repository settings UI, hotkeys, GitHub, developer, and updates surfaces. · `supacode/Features/Settings/Views/SettingsView.swift`
- [Agent presence](https://github.com/supabitapp/supacode/blob/main/supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift): tca feature · Live coding-agent status, badges, avatars, and sidebar cards. · `supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift`
- [Updates](https://github.com/supabitapp/supacode/blob/main/supacode/Features/Updates/Reducer/UpdatesFeature.swift): tca feature · App update state and update flow orchestration. · `supacode/Features/Updates/Reducer/UpdatesFeature.swift`

### Infrastructure

Low-level runtime adapters and local IPC.

- [Ghostty bridge](https://github.com/supabitapp/supacode/blob/main/supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift): runtime adapter · Ghostty runtime, shortcuts, search, split actions, and surface bridging. · `supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift`
- [Agent socket](https://github.com/supabitapp/supacode/blob/main/supacode/Infrastructure/AgentHookSocketServer.swift): local ipc · Local socket server for observing agent activity and payloads. · `supacode/Infrastructure/AgentHookSocketServer.swift`

### CLI

Command-line control plane and transport.

- [CLI entry](https://github.com/supabitapp/supacode/blob/main/supacode-cli/SupacodeCLI.swift): command-line · Supacode CLI entry point and command dispatch surface. · `supacode-cli/SupacodeCLI.swift`
- [CLI transport](https://github.com/supabitapp/supacode/blob/main/supacode-cli/Transport/Dispatcher.swift): ipc client · Dispatcher, query dispatcher, socket discovery, and socket client used by the CLI. · `supacode-cli/Transport/Dispatcher.swift`

### External systems

Git, GitHub, Ghostty, and agent ecosystems the app integrates with.

- **Git**: external vcs · Repository discovery, worktree management, refs, and branch state.
- [GitHub](https://github.com/supabitapp/supacode/blob/main/supacode/Clients/Github/GithubIntegrationClient.swift): external api · GitHub CLI/API integration for pull requests, workflows, merge queue, and repo data. · `supacode/Clients/Github/GithubIntegrationClient.swift`
- [Coding agents](https://github.com/supabitapp/supacode/blob/main/SupacodeSettingsShared/BusinessLogic/AgentIntegration.swift): external integrations · Claude, Codex, Kiro, and Pi hooks, extensions, and settings installers. · `SupacodeSettingsShared/BusinessLogic/AgentIntegration.swift`

## Connections

- Build setup → App shell: builds · Tuist assembles the GUI app and related targets.
- Build setup → CLI entry: builds · Build orchestration also covers the CLI companion.
- Build setup → Native deps: vendors · Native dependencies are built or patched as part of the repo.
- App shell → Content view: hosts · The app entry point renders the main content view.
- Content view → App reducer: drives · Root UI delegates top-level state to the app reducer.
- App reducer → Repositories: coordinates · App flow composes repository selection and worktree actions.
- App reducer → Terminal: coordinates · App flow can open, split, and focus terminal surfaces.
- App reducer → Settings: opens · Global settings are surfaced from app-level navigation.
- App reducer → Agent presence: surfaces · App flow includes agent status and presence affordances.
- Repositories → Sidebar state: uses · Repository feature depends on sidebar persistence and structure logic.
- Repositories → Repo domain: models · Repository feature is built on core repository/worktree types.
- Repositories → Git: reads · Git discovery and worktree state feed repository UI.
- Repositories → GitHub: shows · PR and workflow status are derived from GitHub data.
- Terminal → Tab layout: organizes · Terminal reducers operate on tab and split-layout state.
- Terminal → Ghostty bridge: bridges · Terminal UI is rendered through the Ghostty runtime adapter.
- Terminal → Repo domain: maps · Terminal state is keyed to worktrees and split direction concepts.
- Terminal → Git: binds · Terminal/worktree mapping depends on repository state.
- Settings → Shared core: shares · Settings UI consumes shared settings models and installers.
- Shared core → Coding agents: installs · Shared business logic generates and installs agent hook/settings files.
- Shared core → Git: queries · Settings persistence and repo-local state depend on git/repo queries.
- Agent presence → Agent socket: listens · Presence UI is driven by local agent activity signals.
- Agent socket → Coding agents: observes · Socket server captures external agent hook activity.
- CLI entry → CLI transport: dispatches · CLI commands resolve to local transport actions.
- CLI transport → App shell: targets · CLI transport can address a running app instance via sockets.
- CLI transport → Git: queries · CLI commands can inspect or manipulate repo-local state.
- GitHub → Git: augments · GitHub context is layered on top of repository and branch state.
- Updates → App shell: integrates · Update state is part of the app shell flow.
- Shared core → Repo domain: extends · Shared settings logic builds on common domain concepts.