NEXTERM — Architecture
NEXTERM.xcodeproj (generated by xcodegen from project.yml)
├── Sources/NEXTERM SwiftUI/AppKit app (Swift 6, strict concurrency)
│ ├── App/ NEXTERMApp (scenes), WorkspaceController (+Hosts), Commands, AppSettings,
│ │ PersistenceCoordinator, CompositeLaunchPlanner, DeepLinks
│ ├── Workspace/ WorkspaceWindowView, TabStripView, PaneCanvasView, TerminalHostView,
│ │ WindowAccessor (geometry/key/close, display recovery), StatusBarView
│ ├── Sidebar/ SidebarView (Claude · Hosts · Sessions)
│ ├── Inspector/ InspectorView (verified session facts) + Git panel + Claude section
│ ├── Claude/ ClaudeService (CLI, hook receiver), NotificationService, ClaudeInspectorSection
│ ├── Remote/ HostsSidebarSection, HostEditorSheet
│ ├── Git/ GitPanelView, DiffTextView, GitPanelModel
│ ├── MissionControl/ MissionControlView
│ ├── Settings/ SettingsView (Appearance · Behavior · Claude)
│ └── DesignSystem/ tokens, status glyphs
└── NEXTERMKit (local Swift package, no UI except TerminalCore)
├── WorkspaceCore stable IDs, LayoutNode tree + geometry, Workspace/Window/Tab/Pane models
├── TerminalCore SwiftTerm adapter: NEXTerminalView, TerminalSession, SessionRegistry,
│ LaunchSpec/LaunchPlanning, ProcessInspector (libproc), themes/appearance
├── PersistenceCore SQLiteDatabase, Migrations, WorkspaceStore, SettingsStore, HostStore
├── ClaudeIntegration ClaudeCLI discovery, ClaudeLaunchBuilder, HookEvent/JSONValue,
│ HookSettingsWriter, HookServer (NWListener HTTP/1.1), ClaudeSessionTracker
├── RemoteCore SSHHost, SSHConfigParser (+Include), SSHCommandBuilder, TmuxCommandBuilder
└── GitCore GitRunner (Process, argv), parsers (porcelain v2, log, worktree), GitRepository actorOwnership and lifetimes
SessionRegistry(main actor) owns everyTerminalSession; a session owns itsNEXTerminalView(SwiftTermLocalProcessTerminalView) and therefore the PTY and child process.- SwiftUI never creates or destroys terminal views.
TerminalHostView(NSViewRepresentable) only reparents the session's view into aTerminalContainerView;dismantleNSViewdetaches it. Moving a pane between tabs or windows is a pureWorkspaceStateedit followed by a reparent, so the process is untouched (acceptance test 4). WorkspaceStateis an immutable value tree;WorkspaceControllerapplies edits and callschangeHandler→PersistenceCoordinatorsaves after a 400 ms debounce.
Layout
LayoutNode is leaf(PaneID) | split(id, axis, children, fractions). Same-axis splits are flattened.
frames(in:) lays the tree out in a rect; PaneCanvasView positions each pane absolutely from those
frames (keyed by PaneID, so identities survive splits/swaps) and places DividerHandles on the divider
rects for drag-to-resize (resizing(split:dividerIndex:delta:)). neighbor(of:direction:) drives
⌥⌘-arrow navigation; maximizedPane renders one pane at full size and keeps the others attached but hidden.
Processes
LaunchPlanning turns a SessionProfile into a LaunchSpec (argv, env, cwd, argv[0]).
CompositeLaunchPlanner dispatches: shell/tmux/command → LocalLaunchPlanner; .claude →
ClaudeLaunchBuilder (--session-id/--resume, --settings); .ssh → SSHCommandBuilder.
TerminalSession tracks status from SwiftTerm's process delegate, cwd from OSC 7 plus a 2 s libproc
probe, foreground program via tcgetpgrp + proc_name.
Claude integration
claude --session-id <uuid> --settings <app file> → the CLI POSTs documented hook payloads to
HookServer → ClaudeSessionTracker derives ClaudeSessionInfo.status → Mission Control, sidebar,
inspector and NotificationService (deep link nexterm://pane/<id>). The pane ↔ session link is the
UUID NEXTERM generated; nothing is inferred from terminal text.
Persistence
SQLite schema v1 (Migrations.swift): workspaces → windows → tabs (layout JSON) → panes (profile JSON),
settings (JSON by key), ssh_hosts, claude_sessions, layout_presets. Restoration regenerates session IDs,
starts new processes (banner "new process started"), resumes Claude panes with --resume, and relocates
windows whose display is missing (WindowPlacement.resolveFrame, unit-tested).
Concurrency
Main-actor @Observable models for UI; GitRepository is an actor; HookServer and
SQLiteDatabase are lock-protected Sendable classes; SwiftTerm's I/O runs on its own thread and
hops to the main actor through setProcessOutputHandler (coalesced).
Extension points (optional integrations, P2)
LaunchPlanning— add session kinds without touching TerminalCore.HookEventstream (ClaudeSessionTracker.recentEvents) — observers for AgentOS/AKOS style dashboards.nexterm://URL scheme — external control limited to configured hosts and existing panes.HostStore— host groups such as a MacLustr group are plain data; nothing is hard-coded.