SPB Git

Repository Public

README.md 42.0 KB

NEXTERM logo



NEXTERM icon

# NEXTERM — The Agentic Terminal for macOS

A native macOS terminal and workspace built for running many Claude Code sessions and remote machines side by side. Swift 6, SwiftUI + AppKit, SwiftTerm engine, SQLite persistence — real PTYs, no Electron, no web view.

Author: Simon-Pierre Boucher

version platform distribution license author

Swift SwiftUI SwiftTerm SQLite Network.framework OpenSSH Git tmux Claude Code XcodeGen Xcode Swift Package

commits last commit activity language languages size branches tags clones

Swift files Swift lines package modules SQLite tables themes session kinds kit tests app unit tests acceptance tests ADRs

bundle hardened runtime sandbox launch memory throughput telemetry


# Table of contents


# 📖 Overview

NEXTERM is a production-grade, native macOS terminal and agentic development workspace optimized for Claude Code. Its primary user is a developer operating many Claude Code sessions and remote Mac nodes at the same time. It is a real, usable application — not a mockup, a web wrapper or a decorative terminal: every pane is a pseudo-terminal running a real process.

Platform macOS 15+, Apple Silicon (built and tested on macOS 27.0 / M5 Max)
Terminal engine SwiftTerm 1.99.2 (MIT) — PTY, xterm-256color, truecolor, alt screen, mouse, bracketed paste, Kitty keyboard, OSC 7/8, find
Workspace tabs, nested splits (drag-resize, swap, maximize, ⌥⌘-arrows), multiple windows, pane moves between windows without restarting the process
Persistence versioned SQLite (~/Library/Application Support/NEXTERM/nexterm.sqlite): layouts, window geometry + display, pane profiles, settings, hosts
Claude Code launches the installed claude CLI in a PTY (--session-id, --resume); opt-in observer hooks via --settings (never edits ~/.claude), Mission Control, inspector, native notifications that deep-link to the pane
SSH hosts from ~/.ssh/config, OpenSSH host-key verification in the terminal, reconnect overlay, optional tmux attach, labels/groups/tags/favourites
Git status, history, diffs, worktrees (create; remove only when clean) — Git CLI is the source of truth
Extras command palette (⇧⌘P), nexterm:// deep links, themes, paste protection, focus mode

# Design rules the code holds to

  • Session ownership is decoupled from views. SessionRegistry owns every TerminalSession; SwiftUI only reparents the long-lived NSView. A layout edit never recreates the PTY or resets the shell.
  • Restoration is not reattachment. Restoring a workspace re-creates processes from saved profiles; only tmux-backed and claude --resume sessions genuinely reattach, and the UI says which.
  • Nothing is inferred from terminal text. Session facts come from the kernel (tcgetpgrp, libproc) or from OSC updates; Claude status comes exclusively from documented hook events.
  • Argument arrays, never shell strings. Every child process is launched from a LaunchSpec (argv, env, cwd).
  • Independent. The app is usable without any optional MacLustr, AKOS or AgentOS service; a MacLustr host group is plain data, never a hard-coded assumption.
Repository What it is
nexterm This repository — the agentic terminal and workspace
sp-term SP Term, a separate native macOS terminal by the same author, also built on SwiftTerm

# Documentation in this repository

File Content
docs/PLAN.md inspected environment, milestones, key design rules
docs/PROGRESS.md verified status and acceptance-test evidence
docs/ARCHITECTURE.md modules, ownership and lifetimes, layout, processes, persistence, concurrency, extension points
docs/SECURITY.md process model, entitlements, SSH, hooks, Git, logging, known limitations
docs/SHORTCUTS.md default shortcuts and customisation
docs/PERFORMANCE.md measured launch, memory, CPU, throughput, restoration
docs/RELEASE.md Developer ID signing, notarization, version bumps
docs/ADR/0001-terminal-engine.md why SwiftTerm (libghostty spike)
docs/ADR/0002-claude-hooks-scoped-via-settings-flag.md Claude Code integration through --settings HTTP observer hooks
CLAUDE.md mission, non-negotiable rules, product requirements, acceptance tests

# ✨ Features

# Terminal

  • Real local shell sessions on macOS pseudo-terminals (forkpty through SwiftTerm's LocalProcessTerminalView).
  • xterm-256color, truecolor, alternate screen, mouse reporting, bracketed paste, Kitty keyboard protocol, OSC 7 (working directory) and OSC 8 (hyperlinks).
  • Find bar (⌘F / ⌘G / ⇧⌘G), clear screen and scrollback (⌘K), zoom, scrollback of 10 000 lines (allocated lazily).
  • Paste protection: multi-line pastes prompt for confirmation (on by default); control bytes in pasted text are filtered.
  • 4 built-in themes: NEXTERM Dark, NEXTERM Light, Solarized Dark, Graphite. Option acts as Meta by default.
  • Clickable links and paths go through SwiftTerm's UntrustedTerminalLink validation.

# Workspace

  • Tabs (rename, reorder, close) and nested splits — same-axis splits stay flat.
  • Drag-to-resize dividers, focus ring, maximize / restore, equalize, swap, keyboard navigation (⌥⌘-arrows).
  • Multiple independent windows; Move Pane to New Window keeps the process alive.
  • Exited overlay (Restart / Close), context menu (split / move / close).
  • Closing a pane, tab or window — or quitting — asks first when a foreground program owns the PTY.
  • Sidebar (Claude · Hosts · Sessions), inspector (verified facts: pid, tty, cwd, foreground program), status bar (host, cwd, kind, grid, status, live count), focus mode that hides all chrome.

# Persistence and recovery

  • Versioned SQLite database; debounced saves (400 ms) after every mutation and a save on quit.
  • Restores windows, tabs, pane topology, working directories, profiles and settings on launch.
  • Restored panes show the banner "Layout restored · new process started (previous one was not reattached)"; session identity is regenerated so nothing can be mistaken for reattachment.
  • Window geometry is saved with display id and name; a window whose display is missing is relocated to the main screen.
  • Working-directory tracking: OSC 7 when the shell emits it, plus a libproc probe every 2 s.

# Claude Code

  • Detects the installed claude CLI and its version; never installs or modifies Claude Code.
  • Launches it in an ordinary PTY with --session-id <uuid> (or --resume on restore) — authentication and configuration are untouched.
  • Opt-in observer hooks through --settings <app-private file>: type: http hooks to a loopback receiver. ~/.claude/settings.json is never modified.
  • Session status derived only from hook events: starting, idle, working, waitingForPermission, waitingForInput, ended.
  • Mission Control dashboard, sidebar and inspector sections, native notifications that deep-link to the pane (nexterm://pane/<id>).
  • NEXTERM never answers a permission request or Claude Code's "trust this folder" prompt: the decision stays in the original Claude Code interface.

# SSH and tmux

  • Hosts discovered from ~/.ssh/config (including Include), with labels, groups, tags and favourites stored locally.
  • Always /usr/bin/ssh with StrictHostKeyChecking=ask: unknown hosts prompt in the terminal, changed keys are refused by OpenSSH.
  • Reconnect overlay after a dropped connection; optional tmux attach for genuine reattachment; remote working directory.
  • Authentication uses the user's SSH agent and keys — NEXTERM stores no passwords, passphrases or keys.

# Git

  • Status (porcelain v2), history, diffs and worktrees, read through the Git CLI by a GitRepository actor.
  • Worktrees: create; remove only when clean (the API has no force parameter; dirty worktrees throw GitSafetyError).
  • No merge, push, reset, clean, checkout or branch deletion is exposed. GIT_TERMINAL_PROMPT=0 keeps credential prompts from hanging the app.

# Session kinds

Kind Launch Reattaches on restore
shell the user's login shell no — new process, banner shown
claude claude --session-id / --resume yes, when resumed
ssh /usr/bin/ssh to a configured host, optional tmux session only with tmux
tmux attach to a named tmux session yes
command an executable with an argument array no

# 🧭 Architecture

flowchart TB
  subgraph App["Sources/NEXTERM — SwiftUI + AppKit app"]
    WC["WorkspaceController (+Hosts)<br/>applies edits to WorkspaceState"]
    UI["Workspace views<br/>WorkspaceWindowView · TabStripView · PaneCanvasView · StatusBarView"]
    THV["TerminalHostView<br/>NSViewRepresentable — reparents only"]
    SIDE["Sidebar · Inspector · Git panel · Mission Control · Command palette · Settings"]
    PC["PersistenceCoordinator<br/>400 ms debounce"]
    CLP["CompositeLaunchPlanner"]
    CS["ClaudeService · NotificationService"]
  end
  subgraph Kit["NEXTERMKit — local Swift package"]
    WCORE["WorkspaceCore<br/>stable IDs, LayoutNode tree, models"]
    TCORE["TerminalCore<br/>NEXTerminalView, TerminalSession, SessionRegistry, ProcessInspector"]
    PCORE["PersistenceCore<br/>SQLiteDatabase, Migrations, stores"]
    CI["ClaudeIntegration<br/>ClaudeCLI, HookServer, HookSettings, ClaudeSessionTracker"]
    RC["RemoteCore<br/>SSHHost, config parser, command builders"]
    GC["GitCore<br/>GitRunner, parsers, GitRepository actor"]
  end
  ST["SwiftTerm 1.99.2<br/>PTY + VT emulation + Metal renderer"]
  DB[("nexterm.sqlite")]
  PROC["child processes<br/>zsh · claude · ssh · tmux · git"]
  UI --> WC --> WCORE
  UI --> THV --> TCORE --> ST --> PROC
  WC --> PC --> PCORE --> DB
  WC --> CLP --> TCORE
  CLP --> CI
  CLP --> RC
  SIDE --> GC --> PROC
  CS --> CI
  PROC -. "claude POSTs hook events to 127.0.0.1" .-> CI

# Ownership and lifetimes

  • SessionRegistry (main actor) owns every TerminalSession; a session owns its NEXTerminalView (SwiftTerm LocalProcessTerminalView) and therefore the PTY and the child process.
  • SwiftUI never creates or destroys terminal views. TerminalHostView 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.
  • 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 and swaps) and places DividerHandles on the divider rects for drag-to-resize. 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; .ssh → SSHCommandBuilder. TerminalSession tracks status from SwiftTerm's process delegate, cwd from OSC 7 plus a 2 s libproc probe, and the foreground program through tcgetpgrp + proc_name.

# Claude Code hook flow

sequenceDiagram
  autonumber
  participant N as NEXTERM
  participant F as hooks-settings.json (0600)
  participant C as claude CLI (in a pane)
  participant H as HookServer (127.0.0.1, ephemeral port)
  participant T as ClaudeSessionTracker
  N->>H: start receiver, generate per-launch bearer token
  N->>F: write type http hooks pointing at /hook
  N->>C: claude --session-id UUID --settings FILE
  C->>H: POST /hook (SessionStart, PreToolUse, PermissionRequest, Notification, Stop…)
  H->>H: constant-time token compare, body capped at 2 MB
  H-->>C: 200, empty body — never a decision
  H->>T: HookEvent
  T->>N: status → Mission Control, sidebar, inspector, notification (nexterm://pane/ID)
  Note over N,F: toggle off or quit → receiver stopped, settings file deleted

The pane ↔ session link is the UUID NEXTERM generated and passed to --session-id. Sessions started outside NEXTERM report nothing unless the user passes the same --settings file; Mission Control lists such sessions separately.

# Concurrency

Main-actor @Observable models for the 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 a coalesced output handler.

# Extension points

  • 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 are plain data; nothing is hard-coded.

# 🧰 Stack

Layer Technology Version Role
Language Swift 6.0 language mode, SWIFT_STRICT_CONCURRENCY: complete (toolchain Swift 6.4.2) all code
App shell SwiftUI + AppKit macOS 15.0 deployment target scenes, commands, settings; windows, focus, reparenting
Terminal engine SwiftTerm 1.99.2, pinned exactly (MIT) PTY, VT/xterm emulation, Metal renderer with CoreText fallback
Persistence SQLite 3 (linked sqlite3) schema user_version 1, WAL workspaces, settings, hosts
Hook receiver Network.framework (NWListener) system HTTP/1.1 on loopback
Process inspection libproc, tcgetpgrp system cwd, foreground program
Remote OpenSSH (/usr/bin/ssh), tmux system / user-installed SSH sessions, reattachment
VCS Git CLI user-installed status, log, diff, worktrees
Agent Claude Code CLI verified with 2.1.316 interactive sessions, hooks
Project XcodeGen 2.45.4 used; project.yml generates NEXTERM.xcodeproj
Tooling Xcode 27.2 (27B52) build, unit tests
Architecture arm64 ARCHS: arm64 Apple Silicon only

Transitive pins in NEXTERMKit/Package.resolved (pulled by SwiftTerm): swift-argument-parser 1.8.2, swift-png 4.5.2, h 1.0.1.


# 📁 Repository layout

text
nexterm/
├── CLAUDE.md                 mission + rules for the implementing agent
├── project.yml               xcodegen spec (app, unit tests, UI tests)
├── NEXTERM.xcodeproj/        generated project — never edit by hand
├── NEXTERMKit/               local Swift package (no UI except TerminalCore)
│   ├── Package.swift         6 library products, SwiftTerm pinned to 1.99.2
│   ├── Sources/
│   │   ├── WorkspaceCore/      (4) stable IDs, LayoutNode tree + geometry, Workspace/Window/Tab/Pane models
│   │   ├── TerminalCore/       (6) NEXTerminalView, TerminalSession, SessionRegistry, LaunchSpec, ProcessInspector, appearance
│   │   ├── PersistenceCore/    (6) SQLiteDatabase, Migrations, WorkspaceStore, SettingsStore, HostStore, locations
│   │   ├── ClaudeIntegration/  (5) ClaudeCLI, HookEvent, HookSettings, HookServer, ClaudeSessionTracker
│   │   ├── RemoteCore/         (1) SSHHost, SSH config parser, SSH and tmux command builders
│   │   └── GitCore/            (3) GitRunner, GitModels (parsers), GitRepository actor
│   └── Tests/                  (5) one test target per module except TerminalCore
├── Sources/NEXTERM/          app (26 files)
│   ├── App/                  NEXTERMApp, WorkspaceController (+Hosts), Commands, KeyBindings, AppSettings,
│   │                         PersistenceCoordinator, CompositeLaunchPlanner, DeepLinks
│   ├── Workspace/            WorkspaceWindowView, TabStripView, PaneCanvasView, TerminalHostView, WindowAccessor, StatusBarView
│   ├── Sidebar/              SidebarView (Claude · Hosts · Sessions)
│   ├── Inspector/            InspectorView
│   ├── Claude/               ClaudeService, NotificationService, ClaudeInspectorSection
│   ├── Remote/               HostsSidebarSection
│   ├── Git/                  GitPanelView
│   ├── MissionControl/       MissionControlView
│   ├── Palette/              CommandPalette
│   ├── Settings/             SettingsView
│   └── DesignSystem/         Tokens
├── Resources/                entitlements, asset catalog (icon generated by Scripts/make-icon.swift)
├── Scripts/                  build.sh, smoke-test.sh, perf.sh, release.sh, make-icon.swift, window-shot.swift
├── Tests/                    NEXTERMTests (SmokeTests, WindowPlacementTests), NEXTERMUITests (LaunchUITests)
└── docs/                     PLAN, PROGRESS, ARCHITECTURE, SECURITY, SHORTCUTS, PERFORMANCE, RELEASE, ADR/, brand/

Swift lines: app 3 280 · WorkspaceCore 488 · TerminalCore 711 · PersistenceCore 538 · ClaudeIntegration 526 · RemoteCore 183 · GitCore 319 · kit tests 519 · app tests 93 · scripts 71.


# 🚀 Build

bash
brew install xcodegen            # once
Scripts/build.sh generate        # project.yml → NEXTERM.xcodeproj
Scripts/build.sh debug           # → build/DerivedData/Build/Products/Debug/NEXTERM.app
Scripts/build.sh release         # Release configuration
Scripts/build.sh run             # build debug and launch (stops a running NEXTERM first)
Scripts/build.sh app-path [debug|release]   # print the bundle path
Scripts/build.sh kit-test        # swift test for NEXTERMKit (42 tests)
Scripts/build.sh test            # xcodebuild unit tests (UI tests: see docs/PROGRESS.md)
Scripts/smoke-test.sh            # System Events-driven 8-pane isolation test
Scripts/perf.sh                  # measurements for docs/PERFORMANCE.md
Scripts/release.sh               # Release → Developer ID sign → DMG → notarize → staple
  • Xcode: open NEXTERM.xcodeproj, trust the SwiftTerm build plugin when asked, run the NEXTERM scheme.
  • The Xcode project is generated from project.yml; never edit NEXTERM.xcodeproj by hand.
  • The logic modules build and test without Xcode: swift test --package-path NEXTERMKit.
  • Scripts/build.sh passes -skipPackagePluginValidation (SwiftTerm ships a build-tool plugin) and filters the CoreDevice / CoreSimulator noise that Xcode 27.2 prints on macOS 27.0.
  • Scripts/window-shot.swift NEXTERM out.png captures a window for evidence screenshots; Scripts/make-icon.swift regenerates the app icon.

# 🔧 Configuration

NEXTERM needs no environment variables and ships no secret. Names only:

Name Where Role
-NEXTERMDataDir <dir> launch argument use an isolated data directory instead of Application Support
-NEXTERMFreshWorkspace 1 launch argument start from a fresh workspace instead of restoring
-NEXTERMNoGeometry 1 launch argument do not apply saved window geometry
PANES Scripts/smoke-test.sh number of panes the smoke test opens (default 8)
IDENTITY Scripts/release.sh code-signing identity (default: the Developer ID Application identity of the team)
NOTARY_PROFILE Scripts/release.sh notarytool keychain profile name

Example — launch an isolated instance:

bash
open build/DerivedData/Build/Products/Debug/NEXTERM.app --args -NEXTERMDataDir /tmp/nexterm-test -NEXTERMFreshWorkspace 1

Files the app writes:

Path Content
~/Library/Application Support/NEXTERM/nexterm.sqlite workspaces, settings, hosts (WAL)
~/Library/Application Support/NEXTERM/hooks/hooks-settings.json Claude Code hook settings, mode 0600, only while hooks are enabled

User settings live in the settings table (Settings ▸ Appearance · Behavior · Claude · Keys).


# ⌨ Keyboard shortcuts

All NEXTERM shortcuts use ⌘ so they never reach the shell or TUI programs (which only receive unmodified, ⌃ and ⌥ keys).

Action Default Menu
New Window ⌘N File
New Tab ⌘T File
Close Pane (closes the tab when it is the last pane) ⌘W File
Close Tab ⇧⌘W File
Split Right (vertical divider) ⌘D Shell
Split Down (horizontal divider) ⇧⌘D Shell
Clear Screen and Scrollback ⌘K Shell
Find… / Find Next / Find Previous ⌘F / ⌘G / ⇧⌘G Shell
Focus Next / Previous Pane ⌘] / ⌘[ Pane
Focus Left / Right / Up / Down ⌥⌘ + arrows Pane
Maximize / Restore Pane ⇧⌘↩ Pane
Equalize Panes ⌥⌘= Pane
Move Pane to New Window ⌥⌘N Pane
Next / Previous Tab ⇧⌘] / ⇧⌘[ View
Tab 1 … 8 ⌘1 … ⌘8 View
Show/Hide Sidebar ⌃⌘S View
Show/Hide Inspector ⌃⌘I View
Focus Mode (hide all chrome) ⌃⌘F View
Zoom In / Out / Actual Size ⌘+ / ⌘- / ⌘0 View
Command Palette ⇧⌘P View
Mission Control ⇧⌘M Window
Workspace Switcher ⌃⌘W Window
Copy / Paste / Select All ⌘C / ⌘V / ⌘A Edit
Settings ⌘, NEXTERM

Inside the terminal, the usual control keys (⌃C, ⌃D, ⌃Z, ⌃R…) go straight to the program.

Customisation. Settings ▸ Keys lists every action with its default. Enter a shortcut as cmd+shift+t, ctrl+cmd+g, cmd+return, cmd+] … (modifiers: cmd, shift, option/alt, ctrl; keys: single characters, return, escape, space, tab, delete, arrows). A shortcut must include ⌘ — anything else is rejected so it can never collide with the shell. Conflicts between two actions are flagged in the same pane. Overrides live in the settings table and take effect at the next launch, because SwiftUI builds the menu bar once. Full reference: docs/SHORTCUTS.md.


The nexterm:// scheme only acts on already-configured hosts, existing panes and file-system paths that exist; nothing from a URL reaches a shell.

URL Effect
nexterm://pane/<pane-uuid> focus an existing pane (used by notifications)
nexterm://ssh/<alias>[?tmux=<session>] open a session to a configured SSH host, optionally attaching tmux
nexterm://claude[?dir=<path>] open a Claude Code session, optionally in a directory
nexterm://mission-control show Mission Control

# 💾 Data model

SQLite schema v1 (NEXTERMKit/Sources/PersistenceCore/Migrations.swift), 9 tables. All statements use bound parameters.

Table Key Content
workspaces id name, current flag, timestamps
windows id workspace, position, selected tab, role, frame, display id + name, fullscreen flag
tabs id window, position, custom title, layout JSON, focused and maximized pane
panes id workspace, session id, profile JSON (kind, cwd, label, user-set env overrides)
settings key JSON value, update time
ssh_hosts id alias (unique), hostname, user, port, label, group, tags, tmux session, remote directory, favourite, source
claude_sessions session_id pane, project directory, label, start, last event, status
layout_presets id name, kind, JSON
meta key schema bookkeeping
erDiagram
  workspaces ||--o{ windows : contains
  windows ||--o{ tabs : contains
  workspaces ||--o{ panes : owns
  panes ||--o| claude_sessions : "observed by"
  workspaces {
    TEXT id PK
    TEXT name
    INTEGER is_current
  }
  windows {
    TEXT id PK
    TEXT workspace_id FK
    INTEGER position
    REAL frame_x
    INTEGER display_id
    INTEGER is_fullscreen
  }
  tabs {
    TEXT id PK
    TEXT window_id FK
    TEXT layout_json
    TEXT focused_pane_id
    TEXT maximized_pane_id
  }
  panes {
    TEXT id PK
    TEXT workspace_id FK
    TEXT session_id
    TEXT profile_json
  }
  claude_sessions {
    TEXT session_id PK
    TEXT pane_id
    TEXT status
  }
  ssh_hosts {
    TEXT id PK
    TEXT alias UK
    TEXT group_name
    INTEGER favorite
  }

Stored: layouts, window geometry, pane profiles, settings, host metadata. Never stored: terminal scrollback, credentials, hook tokens.


# 🔒 Security and privacy

Full text: docs/SECURITY.md.

  • Not App Sandboxed, on purpose. NEXTERM must spawn the user's login shell, ssh, git, tmux and claude with the user's real environment and PTYs. Hardened Runtime is enabled. Consequence: distribution is Developer ID + notarization, not the Mac App Store.
  • Terminal output is untrusted. SwiftTerm parses escape sequences; NEXTERM never interprets terminal text as application commands.
  • SSH host keys. There is no code path that sets StrictHostKeyChecking=no or UserKnownHostsFile=/dev/null (tested in RemoteCoreTests). Host aliases are placed after -- so an alias can never be parsed as an option. The one remote-side command string (cd '<dir>' && exec tmux …) single-quotes every user value and strips control characters.
  • Claude Code hooks are observers. Off by default. The receiver listens on 127.0.0.1 on an ephemeral port, authenticates with a constant-time compare of a per-launch bearer token, accepts only POST /hook, caps bodies at 2 MB and always returns an empty 200 — it cannot return permissionDecision, decision, updatedInput or any other directive, so it can never approve, deny or alter a tool call.
  • Git is read-mostly. Read operations, plus git worktree add and removal of a clean worktree.
  • No telemetry, no network calls other than the user's own SSH / Git / Claude processes. Diagnostics use os.Logger (subsystem ai.spboucher.nexterm); terminal contents are never logged and SwiftTerm's raw PTY capture is not enabled anywhere.
  • TCC prompts for Desktop / Documents / Downloads are attributed to NEXTERM when a child process touches those folders, exactly as with Terminal.app. NEXTERM never pre-grants anything.

Known limitations stated by the project:

  • The hook receiver trusts any local process holding the token (the file is 0600 and the token is per launch); a local attacker with the user's privileges could post fake events — these would only affect NEXTERM's status display, never Claude's permission flow.
  • --settings merges with the user's own hook settings; NEXTERM cannot see or control those.
  • If Claude Code restricts http hooks through allowedHttpHookUrls, the user must allow the loopback URL.

# 🧪 Testing

Suite Command Tests Covers
WorkspaceCoreTests Scripts/build.sh kit-test 12 layout tree: split, same-axis flattening, perpendicular nesting, removal and fraction renormalisation, swap, move, resize clamping, frames and neighbours, divider thickness, Codable round trip, workspace consistency
RemoteCoreTests 〃 9 concrete hosts only, Include followed, the real user config read without crashing, host-key checking never disabled, tmux and directory quoted, control characters stripped, alias starting with a dash cannot become an option
ClaudeIntegrationTests 〃 8 payload parsing, settings generation (no permissionDecision ever emitted), 0600 permissions, HTTP parsing, real loopback round trip (200 / 401 / 400)
PersistenceCoreTests 〃 7 migration version, workspace round trip, subtree replace, leaves without pane records dropped, settings round trip, parameter binding (SQL-injection probe), host upsert and list
GitCoreTests 〃 6 porcelain v2 and worktree parsers, branch-name validation, status / log / diff, worktree lifecycle refusing dirty removal, runner not hanging on prompts
NEXTERMKit total 42 swift test, no Xcode needed
NEXTERMTests Scripts/build.sh test 9 WindowPlacementTests (8, simulated display topologies), SmokeTests (1, bundle identifier)
NEXTERMUITests — 1 LaunchUITests — blocked: XCUITest cannot enable automation mode on Xcode 27.2 + macOS 27.0
UI smoke test Scripts/smoke-test.sh 1 scenario 8 panes driven through System Events: each pane owns a distinct PTY, typed text reaches only the focused pane

The smoke test requires Accessibility permission for the invoking terminal and runs in an isolated data directory.

# Acceptance matrix

From docs/PROGRESS.md — verified outcomes only, on the build machine, 2026-11-01.

# Test Status Evidence
1 Local zsh shell interactive PASS typed commands echo tty and $COLUMNS
2 Interactive app + resize PASS vim in alt screen; window resized → grid 109×35, redraw correct
3 8 panes, no cross-session leakage PASS Scripts/smoke-test.sh: 8 shells on 8 ttys, each marker landed in exactly one pane
4 Move live pane between windows PASS sleep 600 pid and tty unchanged after the move; 3 windows
5 Restore layout after restart PASS 1 window / 2 tabs / 4 panes came back
6 Restoration ≠ reattachment PASS banner "new process started", new session IDs and ttys; Claude panes marked "reattached (resume)"
7 Launch installed Claude Code, auth untouched PASS claude 2.1.316 interactive; only --session-id / --settings passed; ~/.claude/settings.json not modified
8 Two Git worktrees in two panes PASS git worktree list shows main + agent/1
9 SSH to authorized host, host-key handling PASS known key → connected; unknown key → OpenSSH prompt, declined, known_hosts unchanged
10 Recover from SSH disconnect / missing monitor PASS (SSH) · partial (monitor) reconnect overlay; display relocation unit-tested, no physical unplug performed
11 Unit + integration + UI smoke + clean Release build PASS (XCUITest runner blocked by environment) kit 42/42, app unit 9/9, smoke test PASS, Release build clean
12 .app bundle launches on build machine PASS dist/NEXTERM.app signed + notarized + stapled; DMG dist/NEXTERM-0.1.0.dmg

# ⚡ Performance

Measured, not estimated — single run on 2026-11-01 with Scripts/perf.sh: Apple M5 Max (18 cores), 48 GB, macOS 27.0, Xcode 27.2, Release configuration, SwiftTerm Metal renderer, Menlo 13 pt. Re-run the script to refresh.

Metric Value Notes
Launch → first window 350 ms fresh workspace, 1 shell
Memory, 1 session 115 MB RSS after 2 s
Memory, 4 / 8 / 16 / 32 sessions 117 / 119 / 124 / 132 MB RSS ≈ 0.55 MB per additional pane (child shells not counted)
Idle CPU, 1–32 sessions 0–0.2 % cumulative ps %cpu
Sustained output 40 MB/s 200 MB via yes | head -c, 32 panes open, app CPU 4.9 % during the burst
Restore a 32-pane workspace window 594 ms, all 32 shells 648 ms layout restored, new processes
Memory after restore 130 MB RSS 32 sessions

Not measured: input latency (no automated keystroke → frame probe yet), memory leaks under Instruments (its CoreDevice plug-in is broken on this Xcode / macOS pair), Intel, multi-GPU, App Nap. Method and caveats: docs/PERFORMANCE.md.


# 📦 Release

Distribution is Developer ID + notarization (the app is not sandboxed, so the Mac App Store is not an option).

bash
Scripts/release.sh                 # build Release, sign, DMG, notarize (--wait), staple
Scripts/release.sh --skip-notarize # local signed build only
Item Value
Bundle id / version ai.spboucher.nexterm, 0.1.0 (1) — MARKETING_VERSION / CURRENT_PROJECT_VERSION in project.yml
Signing Developer ID Application, team 3YM54G49SN, --options runtime --timestamp; Debug builds use Apple Development
Hardened Runtime enabled in project.yml; entitlements in Resources/NEXTERM.entitlements
Notarization notarytool with a keychain profile (NOTARY_PROFILE), --wait, then stapler staple on the DMG and the app
Outputs dist/NEXTERM.app (signed, stapled), dist/NEXTERM-<version>.dmg (signed, notarized, stapled), dist/notarize.log

Pipeline steps: Release build → sign nested code, then the app → codesign --verify and spctl → DMG with an /Applications link → sign the DMG → notarize → staple → final spctl check.

Verification after the pipeline:

bash
codesign --verify --deep --strict --verbose=2 dist/NEXTERM.app
spctl -a -vv -t exec dist/NEXTERM.app        # "accepted … source=Notarized Developer ID"
xcrun stapler validate dist/NEXTERM-*.dmg

Bumping a version: edit MARKETING_VERSION / CURRENT_PROJECT_VERSION in project.yml, run Scripts/build.sh generate, then Scripts/release.sh.

First-run notes for users

  • macOS asks for Accessibility only if you use the System Events smoke test; the app itself needs no special permission.
  • Privacy prompts (Desktop / Documents / Downloads) appear when a shell in NEXTERM touches those folders — same as Terminal.app.
  • Notification permission is requested the first time a Claude hook event needs attention (only if hooks are enabled).

# 🩺 Troubleshooting and gotchas

  • xcodebuild refuses the SwiftTerm plugin → pass -skipPackagePluginValidation (Scripts/build.sh does); in the Xcode IDE, trust the plugin once.
  • App launches with no visible window → this was ProcessInfo.hostName blocking the main thread on reverse DNS; the code uses gethostname. Keep it that way.
  • Empty panes after a reparent → SwiftTerm only recomputes its grid when its frame changes while it is in a window; TerminalContainerView forces a resync when it moves to a window or superview.
  • XCUITest "Timed out while enabling automation mode" on Xcode 27.2 + macOS 27.0 → use Scripts/smoke-test.sh (System Events) instead.
  • Xcode prints CoreDevice / CoreSimulator plug-in errors on macOS 27.0 → noise only for a macOS app; the build helper filters it.
  • Custom shortcuts do not apply immediately → they take effect at the next launch.
  • Claude sessions keep the hooks file path after hooks are turned off → sessions already running keep it on their command line until restarted.
  • Claude Code's "trust this folder" prompt appears for untrusted directories; NEXTERM never answers it.
  • libghostty was evaluated and deferred: the build reached 320 / 337 steps, then needed the Metal Toolchain component, and its C API is marked unstable. The engine sits behind TerminalCore.NEXTerminalView / TerminalSession, so it remains a replaceable implementation detail (ADR 0001).

# 🚧 Status and known limitations

Phases 0–4 are implemented and verified on the build machine, and the Release pipeline produced a signed, notarized and stapled 0.1.0 build; see docs/PROGRESS.md for the acceptance matrix.

  • XCUITest runner blocked by the Xcode 27.2 / macOS 27.0 combination — the UI test target exists but cannot run.
  • Multi-monitor presets (laptop / dual / triple layouts), workspace switcher templates: not yet implemented.
  • Display hot-plug: relocation of a window whose display is missing is unit-tested with simulated topologies; no physical unplug was performed.
  • Custom keybindings need a relaunch.
  • Apple Silicon only (ARCHS: arm64); Intel is neither built nor tested.
  • Input latency and leak profiling are not instrumented.

# 👤 Author


Simon-Pierre Boucher — design, development, operations
www.spboucher.ai · git.spboucher.ai · contact@spboucher.ai


# 📄 License

Private software. All rights reserved © 2026 Simon-Pierre Boucher.

Third-party: SwiftTerm is distributed under the MIT license.

Files main
Menu

Theme