SPB Git

Repository Public

ARCHITECTURE.md 5.1 KB

# NEXTERM — Architecture

text
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 actor

# Ownership and lifetimes

  • SessionRegistry (main actor) owns every TerminalSession; a session owns its NEXTerminalView (SwiftTerm LocalProcessTerminalView) and therefore the PTY and child process.
  • SwiftUI never creates or destroys terminal views. TerminalHostView (NSViewRepresentable) only reparents the session's view into a TerminalContainerView; dismantleNSView detaches it. Moving a pane between tabs or windows is a pure WorkspaceState edit followed by a reparent, so the process is untouched (acceptance test 4).
  • WorkspaceState is an immutable value tree; WorkspaceController applies edits and calls changeHandler → PersistenceCoordinator saves 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.
  • HookEvent stream (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.
Files main
Menu

Theme