Repository Public
1# NEXTERM — Architecture23```4NEXTERM.xcodeproj (generated by xcodegen from project.yml)5├── Sources/NEXTERM SwiftUI/AppKit app (Swift 6, strict concurrency)6│ ├── App/ NEXTERMApp (scenes), WorkspaceController (+Hosts), Commands, AppSettings,7│ │ PersistenceCoordinator, CompositeLaunchPlanner, DeepLinks8│ ├── Workspace/ WorkspaceWindowView, TabStripView, PaneCanvasView, TerminalHostView,9│ │ WindowAccessor (geometry/key/close, display recovery), StatusBarView10│ ├── Sidebar/ SidebarView (Claude · Hosts · Sessions)11│ ├── Inspector/ InspectorView (verified session facts) + Git panel + Claude section12│ ├── Claude/ ClaudeService (CLI, hook receiver), NotificationService, ClaudeInspectorSection13│ ├── Remote/ HostsSidebarSection, HostEditorSheet14│ ├── Git/ GitPanelView, DiffTextView, GitPanelModel15│ ├── MissionControl/ MissionControlView16│ ├── Settings/ SettingsView (Appearance · Behavior · Claude)17│ └── DesignSystem/ tokens, status glyphs18└── NEXTERMKit (local Swift package, no UI except TerminalCore)19 ├── WorkspaceCore stable IDs, LayoutNode tree + geometry, Workspace/Window/Tab/Pane models20 ├── TerminalCore SwiftTerm adapter: NEXTerminalView, TerminalSession, SessionRegistry,21 │ LaunchSpec/LaunchPlanning, ProcessInspector (libproc), themes/appearance22 ├── PersistenceCore SQLiteDatabase, Migrations, WorkspaceStore, SettingsStore, HostStore23 ├── ClaudeIntegration ClaudeCLI discovery, ClaudeLaunchBuilder, HookEvent/JSONValue,24 │ HookSettingsWriter, HookServer (NWListener HTTP/1.1), ClaudeSessionTracker25 ├── RemoteCore SSHHost, SSHConfigParser (+Include), SSHCommandBuilder, TmuxCommandBuilder26 └── GitCore GitRunner (Process, argv), parsers (porcelain v2, log, worktree), GitRepository actor27```2829## Ownership and lifetimes30* `SessionRegistry` (main actor) owns every `TerminalSession`; a session owns its `NEXTerminalView`31 (SwiftTerm `LocalProcessTerminalView`) and therefore the PTY and child process.32* SwiftUI never creates or destroys terminal views. `TerminalHostView` (NSViewRepresentable) only33 **reparents** the session's view into a `TerminalContainerView`; `dismantleNSView` detaches it.34 Moving a pane between tabs or windows is a pure `WorkspaceState` edit followed by a reparent, so the35 process is untouched (acceptance test 4).36* `WorkspaceState` is an immutable value tree; `WorkspaceController` applies edits and calls37 `changeHandler` → `PersistenceCoordinator` saves after a 400 ms debounce.3839## Layout40`LayoutNode` is `leaf(PaneID) | split(id, axis, children, fractions)`. Same-axis splits are flattened.41`frames(in:)` lays the tree out in a rect; `PaneCanvasView` positions each pane absolutely from those42frames (keyed by `PaneID`, so identities survive splits/swaps) and places `DividerHandle`s on the divider43rects for drag-to-resize (`resizing(split:dividerIndex:delta:)`). `neighbor(of:direction:)` drives44⌥⌘-arrow navigation; `maximizedPane` renders one pane at full size and keeps the others attached but hidden.4546## Processes47`LaunchPlanning` turns a `SessionProfile` into a `LaunchSpec` (argv, env, cwd, argv[0]).48`CompositeLaunchPlanner` dispatches: shell/tmux/command → `LocalLaunchPlanner`; `.claude` →49`ClaudeLaunchBuilder` (`--session-id`/`--resume`, `--settings`); `.ssh` → `SSHCommandBuilder`.50`TerminalSession` tracks status from SwiftTerm's process delegate, cwd from OSC 7 plus a 2 s libproc51probe, foreground program via `tcgetpgrp` + `proc_name`.5253## Claude integration54`claude --session-id <uuid> --settings <app file>` → the CLI POSTs documented hook payloads to55`HookServer` → `ClaudeSessionTracker` derives `ClaudeSessionInfo.status` → Mission Control, sidebar,56inspector and `NotificationService` (deep link `nexterm://pane/<id>`). The pane ↔ session link is the57UUID NEXTERM generated; nothing is inferred from terminal text.5859## Persistence60SQLite schema v1 (`Migrations.swift`): workspaces → windows → tabs (layout JSON) → panes (profile JSON),61settings (JSON by key), ssh_hosts, claude_sessions, layout_presets. Restoration regenerates session IDs,62starts new processes (banner "new process started"), resumes Claude panes with `--resume`, and relocates63windows whose display is missing (`WindowPlacement.resolveFrame`, unit-tested).6465## Concurrency66Main-actor `@Observable` models for UI; `GitRepository` is an actor; `HookServer` and67`SQLiteDatabase` are lock-protected `Sendable` classes; SwiftTerm's I/O runs on its own thread and68hops to the main actor through `setProcessOutputHandler` (coalesced).6970## Extension points (optional integrations, P2)71* `LaunchPlanning` — add session kinds without touching TerminalCore.72* `HookEvent` stream (`ClaudeSessionTracker.recentEvents`) — observers for AgentOS/AKOS style dashboards.73* `nexterm://` URL scheme — external control limited to configured hosts and existing panes.74* `HostStore` — host groups such as a MacLustr group are plain data; nothing is hard-coded.75