How umputun/agterm works
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: AppStore.swift Workspace state · ControlServer.swift Control server · agtermApp.swift macOS app · GhosttySurfaceView.swift Terminal surface
Components 26
Desktop app
- macOS app
agterm/agtermApp.swift - App actions
agterm/AppActions.swift - Window and workspace UI
agterm/Views/WindowContentView.swift - Dashboard
agterm/Views/DashboardView.swift - Settings
agterm/SettingsModel.swift
Workspace model
- Window library
agtermCore/Sources/agtermCore/WindowLibrary.swift - Workspace state
agtermCore/Sources/agtermCore/AppStore.swift - Session model
agtermCore/Sources/agtermCore/Session.swift - Saved layout
agtermCore/Sources/agtermCore/Snapshot.swift - State persistence
agtermCore/Sources/agtermCore/PersistenceStore.swift
Terminal runtime
- Terminal surface
agterm/Ghostty/GhosttySurfaceView.swift - Ghostty engine bridge
agterm/Ghostty/GhosttyApp.swift - Command restore
agtermCore/Sources/agtermCore/CommandRestore.swift - Live session manager
agterm/Ghostty/ZmxClient.swift
Control and automation
- agtermctl
agtermCore/Sources/agtermctl/main.swift - CLI commands
agtermCore/Sources/agtermctlKit/Commands.swift - Local socket client
agtermCore/Sources/agtermctlKit/SocketClient.swift - Control server
agterm/Control/ControlServer.swift - HTML overlays
agterm/Views/HtmlOverlayRegistry.swift - Notifications
agterm/Notifications/NotificationManager.swift
Agent and extensions
- Agent status hooks
agterm/AgentHooksInstaller.swift - Agent skill installer
agterm/SkillInstaller.swift - Agent hooks
agtermCore/Sources/agtermCore/Hooks.swift
Other components
- User
- Script or agent
- libghostty
Connections 27
- User → macOS app: uses
README.md - macOS app → App actions: dispatches
agterm/agtermApp.swift - App actions → Workspace state: changes state
agterm/AppActions.swift - macOS app → Window library: manages windows
agterm/agtermApp.swift - Window library → Workspace state: owns stores
agtermCore/Sources/agtermCore/WindowLibrary.swift - Workspace state → Session model: manages sessions
agtermCore/Sources/agtermCore/AppStore.swift - Workspace state → State persistence: persists state
agtermCore/Sources/agtermCore/AppStore.swift - State persistence → Saved layout: reads and writes
agtermCore/Sources/agtermCore/PersistenceStore.swift - Window and workspace UI → Workspace state: displays state
- Session model → Terminal surface: owns surface
agtermCore/Sources/agtermCore/Session.swift - Terminal surface → Ghostty engine bridge: uses engine bridge
agterm/Ghostty/GhosttySurfaceView.swift - Ghostty engine bridge → libghostty: embeds
README.md - Dashboard → Terminal surface: shows sessions
README.md - Settings → Ghostty engine bridge: applies settings
agterm/SettingsModel.swift - macOS app → Command restore: restores layout
- Command restore → Live session manager: keeps processes
README.md - Script or agent → agtermctl: runs commands
README.md - agtermctl → CLI commands: dispatches
- CLI commands → Local socket client: sends requests
agtermCore/Sources/agtermctlKit/SocketClient.swift - Local socket client → Control server: uses local socket
README.md - Control server → Workspace state: drives sessions
agterm/Control/ControlServer+SessionActions.swift - Control server → HTML overlays: controls overlays
agterm/Control/ControlServer+SessionActions.swift - Control server → Notifications: posts notifications
agterm/Control/ControlServer+SessionActions.swift - User → Agent status hooks: installs hooks
README.md - User → Agent skill installer: installs skill
README.md - Agent status hooks → Agent hooks: installs status hooks
- Script or agent → Control server: drives control API
README.md