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
Table of contents
- Overview
- Features
- Architecture
- Stack
- Repository layout
- Build
- Configuration
- Keyboard shortcuts
- Deep links
- Data model
- Security and privacy
- Testing
- Performance
- Release
- Troubleshooting and gotchas
- Status and known limitations
- Author
- License
📖 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.
SessionRegistryowns everyTerminalSession; SwiftUI only reparents the long-livedNSView. 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 --resumesessions 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.
Related repositories
| 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 (
forkptythrough SwiftTerm'sLocalProcessTerminalView). - 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
UntrustedTerminalLinkvalidation.
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
claudeCLI and its version; never installs or modifies Claude Code. - Launches it in an ordinary PTY with
--session-id <uuid>(or--resumeon restore) — authentication and configuration are untouched. - Opt-in observer hooks through
--settings <app-private file>:type: httphooks to a loopback receiver.~/.claude/settings.jsonis 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(includingInclude), with labels, groups, tags and favourites stored locally. - Always
/usr/bin/sshwithStrictHostKeyChecking=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
GitRepositoryactor. - 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=0keeps 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 everyTerminalSession; a session owns itsNEXTerminalView(SwiftTermLocalProcessTerminalView) and therefore the PTY and the child process.- SwiftUI never creates or destroys terminal views.
TerminalHostViewonly 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. 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 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.HookEventstream (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
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
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 theNEXTERMscheme. - The Xcode project is generated from
project.yml; never editNEXTERM.xcodeprojby hand. - The logic modules build and test without Xcode:
swift test --package-path NEXTERMKit. Scripts/build.shpasses-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.pngcaptures a window for evidence screenshots;Scripts/make-icon.swiftregenerates 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:
open build/DerivedData/Build/Products/Debug/NEXTERM.app --args -NEXTERMDataDir /tmp/nexterm-test -NEXTERMFreshWorkspace 1Files 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.
🔗 Deep links
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,tmuxandclaudewith 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=noorUserKnownHostsFile=/dev/null(tested inRemoteCoreTests). 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.1on an ephemeral port, authenticates with a constant-time compare of a per-launch bearer token, accepts onlyPOST /hook, caps bodies at 2 MB and always returns an empty 200 — it cannot returnpermissionDecision,decision,updatedInputor any other directive, so it can never approve, deny or alter a tool call. - Git is read-mostly. Read operations, plus
git worktree addand removal of a clean worktree. - No telemetry, no network calls other than the user's own SSH / Git / Claude processes. Diagnostics use
os.Logger(subsystemai.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.
--settingsmerges 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).
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:
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-*.dmgBumping 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
xcodebuildrefuses the SwiftTerm plugin → pass-skipPackagePluginValidation(Scripts/build.shdoes); in the Xcode IDE, trust the plugin once.- App launches with no visible window → this was
ProcessInfo.hostNameblocking the main thread on reverse DNS; the code usesgethostname. Keep it that way. - Empty panes after a reparent → SwiftTerm only recomputes its grid when its frame changes while it is in a
window;
TerminalContainerViewforces 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.