How supabitapp/supacode works
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: AppFeature.swift App reducer · RepositoriesFeature.swift Repositories · TerminalsFeature.swift Terminal · SupacodeSettingsShared Shared core
Components 21
Tooling
Build, workspace, scripts, and vendored dependencies.
- Build setup · Repo assembly and build orchestration via Tuist, Makefile, workspace, and scripts.
Tuist.swift - Native deps · 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 · Cross-surface settings logic, models, persistence keys, installers, and shared clients.
SupacodeSettingsShared - Repo domain · Core repository, worktree, split-direction, and loading/progress types.
supacode/Domain
GUI app
macOS application shell and top-level orchestration.
- App shell · Main app entry, window lifecycle, telemetry, crash reporting, deeplinks, and command handling.
supacode/App/supacodeApp.swift - Content view · 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 · App coordination feature for deeplinks, command palette, opening worktrees, and global flow.
supacode/Features/App/Reducer/AppFeature.swift - Repositories · Sidebar, worktrees, branch grouping, repo customization, notifications, and PR status.
supacode/Features/Repositories/Reducer/RepositoriesFeature.swift - Sidebar state · Sidebar structure, persistence, grouping, migration, and watcher coordination.
supacode/Features/Repositories/BusinessLogic/SidebarStructure.swift - Terminal · Terminal tabs, split-tree layout, worktree-terminal mapping, persistence, and notifications.
supacode/Features/Terminal/Reducer/TerminalsFeature.swift - Tab layout · Terminal tab identity, split tree, layout snapshots, and worktree surface state.
supacode/Features/Terminal/Models/SplitTree.swift - Settings · Global and repository settings UI, hotkeys, GitHub, developer, and updates surfaces.
supacode/Features/Settings/Views/SettingsView.swift - Agent presence · Live coding-agent status, badges, avatars, and sidebar cards.
supacode/Features/AgentPresence/Reducer/AgentPresenceFeature.swift - Updates · App update state and update flow orchestration.
supacode/Features/Updates/Reducer/UpdatesFeature.swift
Infrastructure
Low-level runtime adapters and local IPC.
- Ghostty bridge · Ghostty runtime, shortcuts, search, split actions, and surface bridging.
supacode/Infrastructure/Ghostty/GhosttySurfaceBridge.swift - Agent socket · Local socket server for observing agent activity and payloads.
supacode/Infrastructure/AgentHookSocketServer.swift
CLI
Command-line control plane and transport.
- CLI entry · Supacode CLI entry point and command dispatch surface.
supacode-cli/SupacodeCLI.swift - CLI transport · 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 · Repository discovery, worktree management, refs, and branch state.
- GitHub · GitHub CLI/API integration for pull requests, workflows, merge queue, and repo data.
supacode/Clients/Github/GithubIntegrationClient.swift - Coding agents · Claude, Codex, Kiro, and Pi hooks, extensions, and settings installers.
SupacodeSettingsShared/BusinessLogic/AgentIntegration.swift
Connections 28
- 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.