# umputun/agterm architecture

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

- Interactive diagram: https://gitdiagram.com/umputun/agterm
- Repository: https://github.com/umputun/agterm

## Overview

agterm is a native macOS terminal organized as windows, named workspaces, sessions, and panes, with a local control API and CLI. The primary workflow is to create or select a session, run a shell in a Ghostty-backed surface, and organize or inspect sessions through the UI or scripts. The graph also includes overlays, dashboard, restore modes, agent status and skill installation, and notifications. Relationship evidence is limited to the README and SOURCE INDEX references; unsampled implementation links are omitted unless documented.

Main entry points: [`agtermCore/Sources/agtermCore/AppStore.swift`](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/AppStore.swift) (Workspace state), [`agterm/Control/ControlServer.swift`](https://github.com/umputun/agterm/blob/master/agterm/Control/ControlServer.swift) (Control server), [`agterm/agtermApp.swift`](https://github.com/umputun/agterm/blob/master/agterm/agtermApp.swift) (macOS app), [`agterm/Ghostty/GhosttySurfaceView.swift`](https://github.com/umputun/agterm/blob/master/agterm/Ghostty/GhosttySurfaceView.swift) (Terminal surface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_app["macOS app<br/>[agtermApp.swift]"]
  node_actions["App actions<br/>[AppActions.swift]"]
  node_views["Window and workspace UI"]
  node_dashboard["Dashboard"]
  node_settings["Settings"]
end

subgraph group_model["Workspace model"]
  node_windows["Window library"]
  node_store["Workspace state<br/>[AppStore.swift]"]
  node_session["Session model<br/>[Session.swift]"]
  node_snapshot["Saved layout<br/>[Snapshot.swift]"]
  node_persistence[("State persistence")]
end

subgraph group_terminal["Terminal runtime"]
  node_surface["Terminal surface"]
  node_ghostty["Ghostty engine bridge<br/>[GhosttyApp.swift]"]
  node_restore["Command restore"]
  node_zmx["Live session manager<br/>[ZmxClient.swift]"]
end

subgraph group_control["Control and automation"]
  node_cli["agtermctl<br/>[main.swift]"]
  node_cli_commands["CLI commands<br/>[Commands.swift]"]
  node_socket["Local socket client<br/>[SocketClient.swift]"]
  node_server["Control server"]
  node_overlay["HTML overlays"]
  node_notifications["Notifications"]
end

subgraph group_extensions["Agent and extensions"]
  node_hooks["Agent status hooks"]
  node_skill["Agent skill installer"]
  node_agent_hooks["Agent hooks<br/>[Hooks.swift]"]
end

node_person(("User"))
node_script(("Script or agent"))
node_terminal_engine["libghostty"]

node_person -->|"uses"| node_app
node_app -->|"dispatches"| node_actions
node_actions -->|"changes state"| node_store
node_app -->|"manages windows"| node_windows
node_windows -->|"owns stores"| node_store
node_store -->|"manages sessions"| node_session
node_store -->|"persists state"| node_persistence
node_persistence -->|"reads and writes"| node_snapshot
node_views -.->|"displays state"| node_store
node_session -->|"owns surface"| node_surface
node_surface -->|"uses engine bridge"| node_ghostty
node_ghostty -->|"embeds"| node_terminal_engine
node_dashboard -->|"shows sessions"| node_surface
node_settings -->|"applies settings"| node_ghostty
node_app -->|"restores layout"| node_restore
node_restore -->|"keeps processes"| node_zmx
node_script -->|"runs commands"| node_cli
node_cli -.->|"dispatches"| node_cli_commands
node_cli_commands -->|"sends requests"| node_socket
node_socket -->|"uses local socket"| node_server
node_server -->|"drives sessions"| node_store
node_server -->|"controls overlays"| node_overlay
node_server -->|"posts notifications"| node_notifications
node_person -->|"installs hooks"| node_hooks
node_person -->|"installs skill"| node_skill
node_hooks -.->|"installs status hooks"| node_agent_hooks
node_script -->|"drives control API"| node_server

click node_app "https://github.com/umputun/agterm/blob/master/agterm/agtermApp.swift"
click node_actions "https://github.com/umputun/agterm/blob/master/agterm/AppActions.swift"
click node_views "https://github.com/umputun/agterm/blob/master/agterm/Views/WindowContentView.swift"
click node_dashboard "https://github.com/umputun/agterm/blob/master/agterm/Views/DashboardView.swift"
click node_settings "https://github.com/umputun/agterm/blob/master/agterm/SettingsModel.swift"
click node_windows "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/WindowLibrary.swift"
click node_store "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/AppStore.swift"
click node_session "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Session.swift"
click node_snapshot "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Snapshot.swift"
click node_persistence "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/PersistenceStore.swift"
click node_surface "https://github.com/umputun/agterm/blob/master/agterm/Ghostty/GhosttySurfaceView.swift"
click node_ghostty "https://github.com/umputun/agterm/blob/master/agterm/Ghostty/GhosttyApp.swift"
click node_restore "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/CommandRestore.swift"
click node_zmx "https://github.com/umputun/agterm/blob/master/agterm/Ghostty/ZmxClient.swift"
click node_cli "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctl/main.swift"
click node_cli_commands "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctlKit/Commands.swift"
click node_socket "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctlKit/SocketClient.swift"
click node_server "https://github.com/umputun/agterm/blob/master/agterm/Control/ControlServer.swift"
click node_overlay "https://github.com/umputun/agterm/blob/master/agterm/Views/HtmlOverlayRegistry.swift"
click node_notifications "https://github.com/umputun/agterm/blob/master/agterm/Notifications/NotificationManager.swift"
click node_hooks "https://github.com/umputun/agterm/blob/master/agterm/AgentHooksInstaller.swift"
click node_skill "https://github.com/umputun/agterm/blob/master/agterm/SkillInstaller.swift"
click node_agent_hooks "https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Hooks.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_app,node_actions,node_views,node_dashboard,node_settings,node_person toneBlue
class node_windows,node_store,node_session,node_snapshot,node_persistence toneAmber
class node_surface,node_ghostty,node_restore,node_zmx toneMint
class node_cli,node_cli_commands,node_socket,node_server,node_overlay,node_notifications toneRose
class node_hooks,node_skill,node_agent_hooks,node_script,node_terminal_engine toneIndigo
```

## Components

### Desktop app

- [macOS app](https://github.com/umputun/agterm/blob/master/agterm/agtermApp.swift): `agterm/agtermApp.swift`
- [App actions](https://github.com/umputun/agterm/blob/master/agterm/AppActions.swift): `agterm/AppActions.swift`
- [Window and workspace UI](https://github.com/umputun/agterm/blob/master/agterm/Views/WindowContentView.swift): `agterm/Views/WindowContentView.swift`
- [Dashboard](https://github.com/umputun/agterm/blob/master/agterm/Views/DashboardView.swift): `agterm/Views/DashboardView.swift`
- [Settings](https://github.com/umputun/agterm/blob/master/agterm/SettingsModel.swift): `agterm/SettingsModel.swift`

### Workspace model

- [Window library](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/WindowLibrary.swift): `agtermCore/Sources/agtermCore/WindowLibrary.swift`
- [Workspace state](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/AppStore.swift): `agtermCore/Sources/agtermCore/AppStore.swift`
- [Session model](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Session.swift): `agtermCore/Sources/agtermCore/Session.swift`
- [Saved layout](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Snapshot.swift): `agtermCore/Sources/agtermCore/Snapshot.swift`
- [State persistence](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/PersistenceStore.swift): `agtermCore/Sources/agtermCore/PersistenceStore.swift`

### Terminal runtime

- [Terminal surface](https://github.com/umputun/agterm/blob/master/agterm/Ghostty/GhosttySurfaceView.swift): `agterm/Ghostty/GhosttySurfaceView.swift`
- [Ghostty engine bridge](https://github.com/umputun/agterm/blob/master/agterm/Ghostty/GhosttyApp.swift): `agterm/Ghostty/GhosttyApp.swift`
- [Command restore](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/CommandRestore.swift): `agtermCore/Sources/agtermCore/CommandRestore.swift`
- [Live session manager](https://github.com/umputun/agterm/blob/master/agterm/Ghostty/ZmxClient.swift): `agterm/Ghostty/ZmxClient.swift`

### Control and automation

- [agtermctl](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctl/main.swift): `agtermCore/Sources/agtermctl/main.swift`
- [CLI commands](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctlKit/Commands.swift): `agtermCore/Sources/agtermctlKit/Commands.swift`
- [Local socket client](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermctlKit/SocketClient.swift): `agtermCore/Sources/agtermctlKit/SocketClient.swift`
- [Control server](https://github.com/umputun/agterm/blob/master/agterm/Control/ControlServer.swift): `agterm/Control/ControlServer.swift`
- [HTML overlays](https://github.com/umputun/agterm/blob/master/agterm/Views/HtmlOverlayRegistry.swift): `agterm/Views/HtmlOverlayRegistry.swift`
- [Notifications](https://github.com/umputun/agterm/blob/master/agterm/Notifications/NotificationManager.swift): `agterm/Notifications/NotificationManager.swift`

### Agent and extensions

- [Agent status hooks](https://github.com/umputun/agterm/blob/master/agterm/AgentHooksInstaller.swift): `agterm/AgentHooksInstaller.swift`
- [Agent skill installer](https://github.com/umputun/agterm/blob/master/agterm/SkillInstaller.swift): `agterm/SkillInstaller.swift`
- [Agent hooks](https://github.com/umputun/agterm/blob/master/agtermCore/Sources/agtermCore/Hooks.swift): `agtermCore/Sources/agtermCore/Hooks.swift`

### Other components

- **User**
- **Script or agent**
- **libghostty**

## Connections

- User → macOS app: uses (evidence: `README.md`)
- macOS app → App actions: dispatches (evidence: `agterm/agtermApp.swift`)
- App actions → Workspace state: changes state (evidence: `agterm/AppActions.swift`)
- macOS app → Window library: manages windows (evidence: `agterm/agtermApp.swift`)
- Window library → Workspace state: owns stores (evidence: `agtermCore/Sources/agtermCore/WindowLibrary.swift`)
- Workspace state → Session model: manages sessions (evidence: `agtermCore/Sources/agtermCore/AppStore.swift`)
- Workspace state → State persistence: persists state (evidence: `agtermCore/Sources/agtermCore/AppStore.swift`)
- State persistence → Saved layout: reads and writes (evidence: `agtermCore/Sources/agtermCore/PersistenceStore.swift`)
- Window and workspace UI → Workspace state: displays state
- Session model → Terminal surface: owns surface (evidence: `agtermCore/Sources/agtermCore/Session.swift`)
- Terminal surface → Ghostty engine bridge: uses engine bridge (evidence: `agterm/Ghostty/GhosttySurfaceView.swift`)
- Ghostty engine bridge → libghostty: embeds (evidence: `README.md`)
- Dashboard → Terminal surface: shows sessions (evidence: `README.md`)
- Settings → Ghostty engine bridge: applies settings (evidence: `agterm/SettingsModel.swift`)
- macOS app → Command restore: restores layout
- Command restore → Live session manager: keeps processes (evidence: `README.md`)
- Script or agent → agtermctl: runs commands (evidence: `README.md`)
- agtermctl → CLI commands: dispatches
- CLI commands → Local socket client: sends requests (evidence: `agtermCore/Sources/agtermctlKit/SocketClient.swift`)
- Local socket client → Control server: uses local socket (evidence: `README.md`)
- Control server → Workspace state: drives sessions (evidence: `agterm/Control/ControlServer+SessionActions.swift`)
- Control server → HTML overlays: controls overlays (evidence: `agterm/Control/ControlServer+SessionActions.swift`)
- Control server → Notifications: posts notifications (evidence: `agterm/Control/ControlServer+SessionActions.swift`)
- User → Agent status hooks: installs hooks (evidence: `README.md`)
- User → Agent skill installer: installs skill (evidence: `README.md`)
- Agent status hooks → Agent hooks: installs status hooks
- Script or agent → Control server: drives control API (evidence: `README.md`)
