Repository Public
1<div align="center">23<img src="docs/brand/logo.svg" alt="NEXTERM logo" width="560">45<br><br>67<img src="docs/brand/icon.png" alt="NEXTERM icon" width="112" height="112">89# NEXTERM — The Agentic Terminal for macOS1011**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.**1213**Author: [Simon-Pierre Boucher](https://www.spboucher.ai)**141516171819202122232425262728293031323334[](https://git.spboucher.ai/nexterm/commits)35[](https://git.spboucher.ai/nexterm/commits)36[](https://git.spboucher.ai/nexterm/insights)37[](https://git.spboucher.ai/nexterm)38[](https://git.spboucher.ai/nexterm/insights)39[](https://git.spboucher.ai/nexterm)40[](https://git.spboucher.ai/nexterm/branches)41[](https://git.spboucher.ai/nexterm/tags)42[](https://git.spboucher.ai/nexterm)434445464748495051525354555657585960616263</div>6465---6667## Table of contents6869- [Overview](#-overview)70- [Features](#-features)71- [Architecture](#-architecture)72- [Stack](#-stack)73- [Repository layout](#-repository-layout)74- [Build](#-build)75- [Configuration](#-configuration)76- [Keyboard shortcuts](#-keyboard-shortcuts)77- [Deep links](#-deep-links)78- [Data model](#-data-model)79- [Security and privacy](#-security-and-privacy)80- [Testing](#-testing)81- [Performance](#-performance)82- [Release](#-release)83- [Troubleshooting and gotchas](#-troubleshooting-and-gotchas)84- [Status and known limitations](#-status-and-known-limitations)85- [Author](#-author)86- [License](#-license)8788---8990## 📖 Overview9192**NEXTERM** is a production-grade, native macOS terminal and agentic development workspace optimized for93[Claude Code](https://code.claude.com). Its primary user is a developer operating many Claude Code sessions and remote94Mac nodes at the same time. It is a real, usable application — not a mockup, a web wrapper or a decorative terminal:95every pane is a pseudo-terminal running a real process.9697| | |98|---|---|99| Platform | macOS 15+, Apple Silicon (built and tested on macOS 27.0 / M5 Max) |100| Terminal engine | [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm) 1.99.2 (MIT) — PTY, xterm-256color, truecolor, alt screen, mouse, bracketed paste, Kitty keyboard, OSC 7/8, find |101| Workspace | tabs, nested splits (drag-resize, swap, maximize, ⌥⌘-arrows), multiple windows, pane moves between windows without restarting the process |102| Persistence | versioned SQLite (`~/Library/Application Support/NEXTERM/nexterm.sqlite`): layouts, window geometry + display, pane profiles, settings, hosts |103| 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 |104| SSH | hosts from `~/.ssh/config`, OpenSSH host-key verification in the terminal, reconnect overlay, optional tmux attach, labels/groups/tags/favourites |105| Git | status, history, diffs, worktrees (create; remove only when clean) — Git CLI is the source of truth |106| Extras | command palette (⇧⌘P), `nexterm://` deep links, themes, paste protection, focus mode |107108### Design rules the code holds to109110- **Session ownership is decoupled from views.** `SessionRegistry` owns every `TerminalSession`; SwiftUI only reparents111 the long-lived `NSView`. A layout edit never recreates the PTY or resets the shell.112- **Restoration is not reattachment.** Restoring a workspace re-creates processes from saved profiles; only113 tmux-backed and `claude --resume` sessions genuinely reattach, and the UI says which.114- **Nothing is inferred from terminal text.** Session facts come from the kernel (`tcgetpgrp`, libproc) or from OSC115 updates; Claude status comes exclusively from documented hook events.116- **Argument arrays, never shell strings.** Every child process is launched from a `LaunchSpec` (argv, env, cwd).117- **Independent.** The app is usable without any optional MacLustr, AKOS or AgentOS service; a MacLustr host group is118 plain data, never a hard-coded assumption.119120### Related repositories121122| Repository | What it is |123|---|---|124| **[nexterm](https://git.spboucher.ai/nexterm)** | **This repository — the agentic terminal and workspace** |125| [sp-term](https://git.spboucher.ai/sp-term) | SP Term, a separate native macOS terminal by the same author, also built on SwiftTerm |126127### Documentation in this repository128129| File | Content |130|---|---|131| [docs/PLAN.md](docs/PLAN.md) | inspected environment, milestones, key design rules |132| [docs/PROGRESS.md](docs/PROGRESS.md) | verified status and acceptance-test evidence |133| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | modules, ownership and lifetimes, layout, processes, persistence, concurrency, extension points |134| [docs/SECURITY.md](docs/SECURITY.md) | process model, entitlements, SSH, hooks, Git, logging, known limitations |135| [docs/SHORTCUTS.md](docs/SHORTCUTS.md) | default shortcuts and customisation |136| [docs/PERFORMANCE.md](docs/PERFORMANCE.md) | measured launch, memory, CPU, throughput, restoration |137| [docs/RELEASE.md](docs/RELEASE.md) | Developer ID signing, notarization, version bumps |138| [docs/ADR/0001-terminal-engine.md](docs/ADR/0001-terminal-engine.md) | why SwiftTerm (libghostty spike) |139| [docs/ADR/0002-claude-hooks-scoped-via-settings-flag.md](docs/ADR/0002-claude-hooks-scoped-via-settings-flag.md) | Claude Code integration through `--settings` HTTP observer hooks |140| [CLAUDE.md](CLAUDE.md) | mission, non-negotiable rules, product requirements, acceptance tests |141142---143144## ✨ Features145146### Terminal147148- Real local shell sessions on macOS pseudo-terminals (`forkpty` through SwiftTerm's `LocalProcessTerminalView`).149- xterm-256color, truecolor, alternate screen, mouse reporting, bracketed paste, Kitty keyboard protocol, OSC 7150 (working directory) and OSC 8 (hyperlinks).151- Find bar (⌘F / ⌘G / ⇧⌘G), clear screen and scrollback (⌘K), zoom, scrollback of 10 000 lines (allocated lazily).152- **Paste protection**: multi-line pastes prompt for confirmation (on by default); control bytes in pasted text are153 filtered.154- 4 built-in themes: **NEXTERM Dark**, **NEXTERM Light**, **Solarized Dark**, **Graphite**. Option acts as Meta by155 default.156- Clickable links and paths go through SwiftTerm's `UntrustedTerminalLink` validation.157158### Workspace159160- Tabs (rename, reorder, close) and nested splits — same-axis splits stay flat.161- Drag-to-resize dividers, focus ring, maximize / restore, equalize, swap, keyboard navigation (⌥⌘-arrows).162- Multiple independent windows; **Move Pane to New Window** keeps the process alive.163- Exited overlay (Restart / Close), context menu (split / move / close).164- Closing a pane, tab or window — or quitting — asks first when a foreground program owns the PTY.165- Sidebar (Claude · Hosts · Sessions), inspector (verified facts: pid, tty, cwd, foreground program), status bar (host,166 cwd, kind, grid, status, live count), **focus mode** that hides all chrome.167168### Persistence and recovery169170- Versioned SQLite database; debounced saves (400 ms) after every mutation and a save on quit.171- Restores windows, tabs, pane topology, working directories, profiles and settings on launch.172- Restored panes show the banner *"Layout restored · new process started (previous one was not reattached)"*; session173 identity is regenerated so nothing can be mistaken for reattachment.174- Window geometry is saved with display id and name; a window whose display is missing is relocated to the main screen.175- Working-directory tracking: OSC 7 when the shell emits it, plus a libproc probe every 2 s.176177### Claude Code178179- Detects the installed `claude` CLI and its version; never installs or modifies Claude Code.180- Launches it in an ordinary PTY with `--session-id <uuid>` (or `--resume` on restore) — authentication and181 configuration are untouched.182- **Opt-in observer hooks** through `--settings <app-private file>`: `type: http` hooks to a loopback receiver.183 `~/.claude/settings.json` is never modified.184- Session status derived only from hook events: `starting`, `idle`, `working`, `waitingForPermission`,185 `waitingForInput`, `ended`.186- **Mission Control** dashboard, sidebar and inspector sections, native notifications that deep-link to the pane187 (`nexterm://pane/<id>`).188- NEXTERM never answers a permission request or Claude Code's "trust this folder" prompt: the decision stays in the189 original Claude Code interface.190191### SSH and tmux192193- Hosts discovered from `~/.ssh/config` (including `Include`), with labels, groups, tags and favourites stored locally.194- Always `/usr/bin/ssh` with `StrictHostKeyChecking=ask`: unknown hosts prompt **in the terminal**, changed keys are195 refused by OpenSSH.196- Reconnect overlay after a dropped connection; optional tmux attach for genuine reattachment; remote working directory.197- Authentication uses the user's SSH agent and keys — NEXTERM stores no passwords, passphrases or keys.198199### Git200201- Status (porcelain v2), history, diffs and worktrees, read through the Git CLI by a `GitRepository` actor.202- Worktrees: create; remove **only when clean** (the API has no force parameter; dirty worktrees throw203 `GitSafetyError`).204- No merge, push, reset, clean, checkout or branch deletion is exposed. `GIT_TERMINAL_PROMPT=0` keeps credential205 prompts from hanging the app.206207### Session kinds208209| Kind | Launch | Reattaches on restore |210|---|---|---|211| `shell` | the user's login shell | no — new process, banner shown |212| `claude` | `claude --session-id` / `--resume` | yes, when resumed |213| `ssh` | `/usr/bin/ssh` to a configured host, optional tmux session | only with tmux |214| `tmux` | attach to a named tmux session | yes |215| `command` | an executable with an argument array | no |216217---218219## 🧭 Architecture220221```mermaid222flowchart TB223 subgraph App["Sources/NEXTERM — SwiftUI + AppKit app"]224 WC["WorkspaceController (+Hosts)<br/>applies edits to WorkspaceState"]225 UI["Workspace views<br/>WorkspaceWindowView · TabStripView · PaneCanvasView · StatusBarView"]226 THV["TerminalHostView<br/>NSViewRepresentable — reparents only"]227 SIDE["Sidebar · Inspector · Git panel · Mission Control · Command palette · Settings"]228 PC["PersistenceCoordinator<br/>400 ms debounce"]229 CLP["CompositeLaunchPlanner"]230 CS["ClaudeService · NotificationService"]231 end232 subgraph Kit["NEXTERMKit — local Swift package"]233 WCORE["WorkspaceCore<br/>stable IDs, LayoutNode tree, models"]234 TCORE["TerminalCore<br/>NEXTerminalView, TerminalSession, SessionRegistry, ProcessInspector"]235 PCORE["PersistenceCore<br/>SQLiteDatabase, Migrations, stores"]236 CI["ClaudeIntegration<br/>ClaudeCLI, HookServer, HookSettings, ClaudeSessionTracker"]237 RC["RemoteCore<br/>SSHHost, config parser, command builders"]238 GC["GitCore<br/>GitRunner, parsers, GitRepository actor"]239 end240 ST["SwiftTerm 1.99.2<br/>PTY + VT emulation + Metal renderer"]241 DB[("nexterm.sqlite")]242 PROC["child processes<br/>zsh · claude · ssh · tmux · git"]243 UI --> WC --> WCORE244 UI --> THV --> TCORE --> ST --> PROC245 WC --> PC --> PCORE --> DB246 WC --> CLP --> TCORE247 CLP --> CI248 CLP --> RC249 SIDE --> GC --> PROC250 CS --> CI251 PROC -. "claude POSTs hook events to 127.0.0.1" .-> CI252```253254### Ownership and lifetimes255256- `SessionRegistry` (main actor) owns every `TerminalSession`; a session owns its `NEXTerminalView` (SwiftTerm257 `LocalProcessTerminalView`) and therefore the PTY and the child process.258- SwiftUI never creates or destroys terminal views. `TerminalHostView` only **reparents** the session's view into a259 `TerminalContainerView`; `dismantleNSView` detaches it. Moving a pane between tabs or windows is a pure260 `WorkspaceState` edit followed by a reparent, so the process is untouched.261- `WorkspaceState` is an immutable value tree; `WorkspaceController` applies edits and calls `changeHandler` →262 `PersistenceCoordinator` saves after a 400 ms debounce.263264### Layout265266`LayoutNode` is `leaf(PaneID) | split(id, axis, children, fractions)`. Same-axis splits are flattened. `frames(in:)`267lays the tree out in a rect; `PaneCanvasView` positions each pane absolutely from those frames (keyed by `PaneID`, so268identities survive splits and swaps) and places `DividerHandle`s on the divider rects for drag-to-resize.269`neighbor(of:direction:)` drives ⌥⌘-arrow navigation; `maximizedPane` renders one pane at full size and keeps the270others attached but hidden.271272### Processes273274`LaunchPlanning` turns a `SessionProfile` into a `LaunchSpec` (argv, env, cwd, argv[0]). `CompositeLaunchPlanner`275dispatches: shell / tmux / command → `LocalLaunchPlanner`; `.claude` → `ClaudeLaunchBuilder`; `.ssh` →276`SSHCommandBuilder`. `TerminalSession` tracks status from SwiftTerm's process delegate, cwd from OSC 7 plus a 2 s277libproc probe, and the foreground program through `tcgetpgrp` + `proc_name`.278279### Claude Code hook flow280281```mermaid282sequenceDiagram283 autonumber284 participant N as NEXTERM285 participant F as hooks-settings.json (0600)286 participant C as claude CLI (in a pane)287 participant H as HookServer (127.0.0.1, ephemeral port)288 participant T as ClaudeSessionTracker289 N->>H: start receiver, generate per-launch bearer token290 N->>F: write type http hooks pointing at /hook291 N->>C: claude --session-id UUID --settings FILE292 C->>H: POST /hook (SessionStart, PreToolUse, PermissionRequest, Notification, Stop…)293 H->>H: constant-time token compare, body capped at 2 MB294 H-->>C: 200, empty body — never a decision295 H->>T: HookEvent296 T->>N: status → Mission Control, sidebar, inspector, notification (nexterm://pane/ID)297 Note over N,F: toggle off or quit → receiver stopped, settings file deleted298```299300The pane ↔ session link is the UUID NEXTERM generated and passed to `--session-id`. Sessions started outside NEXTERM301report nothing unless the user passes the same `--settings` file; Mission Control lists such sessions separately.302303### Concurrency304305Main-actor `@Observable` models for the UI; `GitRepository` is an actor; `HookServer` and `SQLiteDatabase` are306lock-protected `Sendable` classes; SwiftTerm's I/O runs on its own thread and hops to the main actor through a307coalesced output handler.308309### Extension points310311- `LaunchPlanning` — add session kinds without touching TerminalCore.312- `HookEvent` stream (`ClaudeSessionTracker.recentEvents`) — observers for AgentOS / AKOS style dashboards.313- `nexterm://` URL scheme — external control limited to configured hosts and existing panes.314- `HostStore` — host groups are plain data; nothing is hard-coded.315316---317318## 🧰 Stack319320| Layer | Technology | Version | Role |321|---|---|---|---|322| Language | Swift | 6.0 language mode, `SWIFT_STRICT_CONCURRENCY: complete` (toolchain Swift 6.4.2) | all code |323| App shell | SwiftUI + AppKit | macOS 15.0 deployment target | scenes, commands, settings; windows, focus, reparenting |324| Terminal engine | SwiftTerm | 1.99.2, pinned exactly (MIT) | PTY, VT/xterm emulation, Metal renderer with CoreText fallback |325| Persistence | SQLite 3 (linked `sqlite3`) | schema `user_version` 1, WAL | workspaces, settings, hosts |326| Hook receiver | Network.framework (`NWListener`) | system | HTTP/1.1 on loopback |327| Process inspection | libproc, `tcgetpgrp` | system | cwd, foreground program |328| Remote | OpenSSH (`/usr/bin/ssh`), tmux | system / user-installed | SSH sessions, reattachment |329| VCS | Git CLI | user-installed | status, log, diff, worktrees |330| Agent | Claude Code CLI | verified with 2.1.316 | interactive sessions, hooks |331| Project | XcodeGen | 2.45.4 used; `project.yml` | generates `NEXTERM.xcodeproj` |332| Tooling | Xcode | 27.2 (27B52) | build, unit tests |333| Architecture | arm64 | `ARCHS: arm64` | Apple Silicon only |334335Transitive pins in `NEXTERMKit/Package.resolved` (pulled by SwiftTerm): swift-argument-parser 1.8.2, swift-png 4.5.2,336`h` 1.0.1.337338---339340## 📁 Repository layout341342```343nexterm/344├── CLAUDE.md mission + rules for the implementing agent345├── project.yml xcodegen spec (app, unit tests, UI tests)346├── NEXTERM.xcodeproj/ generated project — never edit by hand347├── NEXTERMKit/ local Swift package (no UI except TerminalCore)348│ ├── Package.swift 6 library products, SwiftTerm pinned to 1.99.2349│ ├── Sources/350│ │ ├── WorkspaceCore/ (4) stable IDs, LayoutNode tree + geometry, Workspace/Window/Tab/Pane models351│ │ ├── TerminalCore/ (6) NEXTerminalView, TerminalSession, SessionRegistry, LaunchSpec, ProcessInspector, appearance352│ │ ├── PersistenceCore/ (6) SQLiteDatabase, Migrations, WorkspaceStore, SettingsStore, HostStore, locations353│ │ ├── ClaudeIntegration/ (5) ClaudeCLI, HookEvent, HookSettings, HookServer, ClaudeSessionTracker354│ │ ├── RemoteCore/ (1) SSHHost, SSH config parser, SSH and tmux command builders355│ │ └── GitCore/ (3) GitRunner, GitModels (parsers), GitRepository actor356│ └── Tests/ (5) one test target per module except TerminalCore357├── Sources/NEXTERM/ app (26 files)358│ ├── App/ NEXTERMApp, WorkspaceController (+Hosts), Commands, KeyBindings, AppSettings,359│ │ PersistenceCoordinator, CompositeLaunchPlanner, DeepLinks360│ ├── Workspace/ WorkspaceWindowView, TabStripView, PaneCanvasView, TerminalHostView, WindowAccessor, StatusBarView361│ ├── Sidebar/ SidebarView (Claude · Hosts · Sessions)362│ ├── Inspector/ InspectorView363│ ├── Claude/ ClaudeService, NotificationService, ClaudeInspectorSection364│ ├── Remote/ HostsSidebarSection365│ ├── Git/ GitPanelView366│ ├── MissionControl/ MissionControlView367│ ├── Palette/ CommandPalette368│ ├── Settings/ SettingsView369│ └── DesignSystem/ Tokens370├── Resources/ entitlements, asset catalog (icon generated by Scripts/make-icon.swift)371├── Scripts/ build.sh, smoke-test.sh, perf.sh, release.sh, make-icon.swift, window-shot.swift372├── Tests/ NEXTERMTests (SmokeTests, WindowPlacementTests), NEXTERMUITests (LaunchUITests)373└── docs/ PLAN, PROGRESS, ARCHITECTURE, SECURITY, SHORTCUTS, PERFORMANCE, RELEASE, ADR/, brand/374```375376Swift lines: app 3 280 · WorkspaceCore 488 · TerminalCore 711 · PersistenceCore 538 · ClaudeIntegration 526 ·377RemoteCore 183 · GitCore 319 · kit tests 519 · app tests 93 · scripts 71.378379---380381## 🚀 Build382383```bash384brew install xcodegen # once385Scripts/build.sh generate # project.yml → NEXTERM.xcodeproj386Scripts/build.sh debug # → build/DerivedData/Build/Products/Debug/NEXTERM.app387Scripts/build.sh release # Release configuration388Scripts/build.sh run # build debug and launch (stops a running NEXTERM first)389Scripts/build.sh app-path [debug|release] # print the bundle path390Scripts/build.sh kit-test # swift test for NEXTERMKit (42 tests)391Scripts/build.sh test # xcodebuild unit tests (UI tests: see docs/PROGRESS.md)392Scripts/smoke-test.sh # System Events-driven 8-pane isolation test393Scripts/perf.sh # measurements for docs/PERFORMANCE.md394Scripts/release.sh # Release → Developer ID sign → DMG → notarize → staple395```396397- **Xcode**: open `NEXTERM.xcodeproj`, trust the SwiftTerm build plugin when asked, run the `NEXTERM` scheme.398- The Xcode project is generated from `project.yml`; never edit `NEXTERM.xcodeproj` by hand.399- The logic modules build and test without Xcode: `swift test --package-path NEXTERMKit`.400- `Scripts/build.sh` passes `-skipPackagePluginValidation` (SwiftTerm ships a build-tool plugin) and filters the401 CoreDevice / CoreSimulator noise that Xcode 27.2 prints on macOS 27.0.402- `Scripts/window-shot.swift NEXTERM out.png` captures a window for evidence screenshots;403 `Scripts/make-icon.swift` regenerates the app icon.404405---406407## 🔧 Configuration408409NEXTERM needs no environment variables and ships no secret. Names only:410411| Name | Where | Role |412|---|---|---|413| `-NEXTERMDataDir <dir>` | launch argument | use an isolated data directory instead of Application Support |414| `-NEXTERMFreshWorkspace 1` | launch argument | start from a fresh workspace instead of restoring |415| `-NEXTERMNoGeometry 1` | launch argument | do not apply saved window geometry |416| `PANES` | `Scripts/smoke-test.sh` | number of panes the smoke test opens (default 8) |417| `IDENTITY` | `Scripts/release.sh` | code-signing identity (default: the Developer ID Application identity of the team) |418| `NOTARY_PROFILE` | `Scripts/release.sh` | `notarytool` keychain profile name |419420Example — launch an isolated instance:421422```bash423open build/DerivedData/Build/Products/Debug/NEXTERM.app --args -NEXTERMDataDir /tmp/nexterm-test -NEXTERMFreshWorkspace 1424```425426Files the app writes:427428| Path | Content |429|---|---|430| `~/Library/Application Support/NEXTERM/nexterm.sqlite` | workspaces, settings, hosts (WAL) |431| `~/Library/Application Support/NEXTERM/hooks/hooks-settings.json` | Claude Code hook settings, mode 0600, only while hooks are enabled |432433User settings live in the `settings` table (Settings ▸ Appearance · Behavior · Claude · Keys).434435---436437## ⌨ Keyboard shortcuts438439All NEXTERM shortcuts use ⌘ so they never reach the shell or TUI programs (which only receive unmodified, ⌃ and ⌥440keys).441442| Action | Default | Menu |443|---|---|---|444| New Window | <kbd>⌘</kbd><kbd>N</kbd> | File |445| New Tab | <kbd>⌘</kbd><kbd>T</kbd> | File |446| Close Pane (closes the tab when it is the last pane) | <kbd>⌘</kbd><kbd>W</kbd> | File |447| Close Tab | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>W</kbd> | File |448| Split Right (vertical divider) | <kbd>⌘</kbd><kbd>D</kbd> | Shell |449| Split Down (horizontal divider) | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>D</kbd> | Shell |450| Clear Screen and Scrollback | <kbd>⌘</kbd><kbd>K</kbd> | Shell |451| Find… / Find Next / Find Previous | <kbd>⌘</kbd><kbd>F</kbd> / <kbd>⌘</kbd><kbd>G</kbd> / <kbd>⇧</kbd><kbd>⌘</kbd><kbd>G</kbd> | Shell |452| Focus Next / Previous Pane | <kbd>⌘</kbd><kbd>]</kbd> / <kbd>⌘</kbd><kbd>[</kbd> | Pane |453| Focus Left / Right / Up / Down | <kbd>⌥</kbd><kbd>⌘</kbd> + arrows | Pane |454| Maximize / Restore Pane | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>↩</kbd> | Pane |455| Equalize Panes | <kbd>⌥</kbd><kbd>⌘</kbd><kbd>=</kbd> | Pane |456| Move Pane to New Window | <kbd>⌥</kbd><kbd>⌘</kbd><kbd>N</kbd> | Pane |457| Next / Previous Tab | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>]</kbd> / <kbd>⇧</kbd><kbd>⌘</kbd><kbd>[</kbd> | View |458| Tab 1 … 8 | <kbd>⌘</kbd><kbd>1</kbd> … <kbd>⌘</kbd><kbd>8</kbd> | View |459| Show/Hide Sidebar | <kbd>⌃</kbd><kbd>⌘</kbd><kbd>S</kbd> | View |460| Show/Hide Inspector | <kbd>⌃</kbd><kbd>⌘</kbd><kbd>I</kbd> | View |461| Focus Mode (hide all chrome) | <kbd>⌃</kbd><kbd>⌘</kbd><kbd>F</kbd> | View |462| Zoom In / Out / Actual Size | <kbd>⌘</kbd><kbd>+</kbd> / <kbd>⌘</kbd><kbd>-</kbd> / <kbd>⌘</kbd><kbd>0</kbd> | View |463| Command Palette | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>P</kbd> | View |464| Mission Control | <kbd>⇧</kbd><kbd>⌘</kbd><kbd>M</kbd> | Window |465| Workspace Switcher | <kbd>⌃</kbd><kbd>⌘</kbd><kbd>W</kbd> | Window |466| Copy / Paste / Select All | <kbd>⌘</kbd><kbd>C</kbd> / <kbd>⌘</kbd><kbd>V</kbd> / <kbd>⌘</kbd><kbd>A</kbd> | Edit |467| Settings | <kbd>⌘</kbd><kbd>,</kbd> | NEXTERM |468469Inside the terminal, the usual control keys (⌃C, ⌃D, ⌃Z, ⌃R…) go straight to the program.470471**Customisation.** Settings ▸ Keys lists every action with its default. Enter a shortcut as `cmd+shift+t`,472`ctrl+cmd+g`, `cmd+return`, `cmd+]` … (modifiers: cmd, shift, option/alt, ctrl; keys: single characters, return,473escape, space, tab, delete, arrows). A shortcut must include ⌘ — anything else is rejected so it can never collide474with the shell. Conflicts between two actions are flagged in the same pane. Overrides live in the settings table and475take effect at the next launch, because SwiftUI builds the menu bar once. Full reference:476[docs/SHORTCUTS.md](docs/SHORTCUTS.md).477478---479480## 🔗 Deep links481482The `nexterm://` scheme only acts on already-configured hosts, existing panes and file-system paths that exist;483nothing from a URL reaches a shell.484485| URL | Effect |486|---|---|487| `nexterm://pane/<pane-uuid>` | focus an existing pane (used by notifications) |488| `nexterm://ssh/<alias>[?tmux=<session>]` | open a session to a configured SSH host, optionally attaching tmux |489| `nexterm://claude[?dir=<path>]` | open a Claude Code session, optionally in a directory |490| `nexterm://mission-control` | show Mission Control |491492---493494## 💾 Data model495496SQLite schema v1 (`NEXTERMKit/Sources/PersistenceCore/Migrations.swift`), 9 tables. All statements use bound497parameters.498499| Table | Key | Content |500|---|---|---|501| `workspaces` | `id` | name, current flag, timestamps |502| `windows` | `id` | workspace, position, selected tab, role, frame, display id + name, fullscreen flag |503| `tabs` | `id` | window, position, custom title, **layout JSON**, focused and maximized pane |504| `panes` | `id` | workspace, session id, **profile JSON** (kind, cwd, label, user-set env overrides) |505| `settings` | `key` | JSON value, update time |506| `ssh_hosts` | `id` | alias (unique), hostname, user, port, label, group, tags, tmux session, remote directory, favourite, source |507| `claude_sessions` | `session_id` | pane, project directory, label, start, last event, status |508| `layout_presets` | `id` | name, kind, JSON |509| `meta` | `key` | schema bookkeeping |510511```mermaid512erDiagram513 workspaces ||--o{ windows : contains514 windows ||--o{ tabs : contains515 workspaces ||--o{ panes : owns516 panes ||--o| claude_sessions : "observed by"517 workspaces {518 TEXT id PK519 TEXT name520 INTEGER is_current521 }522 windows {523 TEXT id PK524 TEXT workspace_id FK525 INTEGER position526 REAL frame_x527 INTEGER display_id528 INTEGER is_fullscreen529 }530 tabs {531 TEXT id PK532 TEXT window_id FK533 TEXT layout_json534 TEXT focused_pane_id535 TEXT maximized_pane_id536 }537 panes {538 TEXT id PK539 TEXT workspace_id FK540 TEXT session_id541 TEXT profile_json542 }543 claude_sessions {544 TEXT session_id PK545 TEXT pane_id546 TEXT status547 }548 ssh_hosts {549 TEXT id PK550 TEXT alias UK551 TEXT group_name552 INTEGER favorite553 }554```555556**Stored**: layouts, window geometry, pane profiles, settings, host metadata.557**Never stored**: terminal scrollback, credentials, hook tokens.558559---560561## 🔒 Security and privacy562563Full text: [docs/SECURITY.md](docs/SECURITY.md).564565- **Not App Sandboxed, on purpose.** NEXTERM must spawn the user's login shell, `ssh`, `git`, `tmux` and `claude` with566 the user's real environment and PTYs. Hardened Runtime is enabled. Consequence: distribution is Developer ID +567 notarization, not the Mac App Store.568- **Terminal output is untrusted.** SwiftTerm parses escape sequences; NEXTERM never interprets terminal text as569 application commands.570- **SSH host keys.** There is no code path that sets `StrictHostKeyChecking=no` or `UserKnownHostsFile=/dev/null`571 (tested in `RemoteCoreTests`). Host aliases are placed after `--` so an alias can never be parsed as an option. The572 one remote-side command string (`cd '<dir>' && exec tmux …`) single-quotes every user value and strips control573 characters.574- **Claude Code hooks are observers.** Off by default. The receiver listens on `127.0.0.1` on an ephemeral port,575 authenticates with a constant-time compare of a per-launch bearer token, accepts only `POST /hook`, caps bodies at576 2 MB and **always returns an empty 200** — it cannot return `permissionDecision`, `decision`, `updatedInput` or any577 other directive, so it can never approve, deny or alter a tool call.578- **Git is read-mostly.** Read operations, plus `git worktree add` and removal of a *clean* worktree.579- **No telemetry**, no network calls other than the user's own SSH / Git / Claude processes. Diagnostics use580 `os.Logger` (subsystem `ai.spboucher.nexterm`); terminal contents are never logged and SwiftTerm's raw PTY capture is581 not enabled anywhere.582- **TCC prompts** for Desktop / Documents / Downloads are attributed to NEXTERM when a child process touches those583 folders, exactly as with Terminal.app. NEXTERM never pre-grants anything.584585Known limitations stated by the project:586587- The hook receiver trusts any local process holding the token (the file is 0600 and the token is per launch); a local588 attacker with the user's privileges could post fake events — these would only affect NEXTERM's status display, never589 Claude's permission flow.590- `--settings` merges with the user's own hook settings; NEXTERM cannot see or control those.591- If Claude Code restricts http hooks through `allowedHttpHookUrls`, the user must allow the loopback URL.592593---594595## 🧪 Testing596597| Suite | Command | Tests | Covers |598|---|---|---|---|599| `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 |600| `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 |601| `ClaudeIntegrationTests` | 〃 | 8 | payload parsing, settings generation (no `permissionDecision` ever emitted), 0600 permissions, HTTP parsing, real loopback round trip (200 / 401 / 400) |602| `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 |603| `GitCoreTests` | 〃 | 6 | porcelain v2 and worktree parsers, branch-name validation, status / log / diff, worktree lifecycle refusing dirty removal, runner not hanging on prompts |604| **NEXTERMKit total** | | **42** | `swift test`, no Xcode needed |605| `NEXTERMTests` | `Scripts/build.sh test` | 9 | `WindowPlacementTests` (8, simulated display topologies), `SmokeTests` (1, bundle identifier) |606| `NEXTERMUITests` | — | 1 | `LaunchUITests` — **blocked**: XCUITest cannot enable automation mode on Xcode 27.2 + macOS 27.0 |607| 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 |608609The smoke test requires Accessibility permission for the invoking terminal and runs in an isolated data directory.610611### Acceptance matrix612613From [docs/PROGRESS.md](docs/PROGRESS.md) — verified outcomes only, on the build machine, 2026-11-01.614615| # | Test | Status | Evidence |616|---|---|---|---|617| 1 | Local zsh shell interactive | PASS | typed commands echo tty and `$COLUMNS` |618| 2 | Interactive app + resize | PASS | vim in alt screen; window resized → grid 109×35, redraw correct |619| 3 | 8 panes, no cross-session leakage | PASS | `Scripts/smoke-test.sh`: 8 shells on 8 ttys, each marker landed in exactly one pane |620| 4 | Move live pane between windows | PASS | `sleep 600` pid and tty unchanged after the move; 3 windows |621| 5 | Restore layout after restart | PASS | 1 window / 2 tabs / 4 panes came back |622| 6 | Restoration ≠ reattachment | PASS | banner "new process started", new session IDs and ttys; Claude panes marked "reattached (resume)" |623| 7 | Launch installed Claude Code, auth untouched | PASS | claude 2.1.316 interactive; only `--session-id` / `--settings` passed; `~/.claude/settings.json` not modified |624| 8 | Two Git worktrees in two panes | PASS | `git worktree list` shows main + `agent/1` |625| 9 | SSH to authorized host, host-key handling | PASS | known key → connected; unknown key → OpenSSH prompt, declined, `known_hosts` unchanged |626| 10 | Recover from SSH disconnect / missing monitor | PASS (SSH) · partial (monitor) | reconnect overlay; display relocation unit-tested, no physical unplug performed |627| 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 |628| 12 | `.app` bundle launches on build machine | PASS | `dist/NEXTERM.app` signed + notarized + stapled; DMG `dist/NEXTERM-0.1.0.dmg` |629630---631632## ⚡ Performance633634Measured, not estimated — single run on 2026-11-01 with `Scripts/perf.sh`: Apple M5 Max (18 cores), 48 GB, macOS 27.0,635Xcode 27.2, Release configuration, SwiftTerm Metal renderer, Menlo 13 pt. Re-run the script to refresh.636637| Metric | Value | Notes |638|---|---|---|639| Launch → first window | 350 ms | fresh workspace, 1 shell |640| Memory, 1 session | 115 MB RSS | after 2 s |641| Memory, 4 / 8 / 16 / 32 sessions | 117 / 119 / 124 / 132 MB RSS | ≈ 0.55 MB per additional pane (child shells not counted) |642| Idle CPU, 1–32 sessions | 0–0.2 % | cumulative `ps %cpu` |643| Sustained output | 40 MB/s | 200 MB via `yes \| head -c`, 32 panes open, app CPU 4.9 % during the burst |644| Restore a 32-pane workspace | window 594 ms, all 32 shells 648 ms | layout restored, new processes |645| Memory after restore | 130 MB RSS | 32 sessions |646647Not measured: input latency (no automated keystroke → frame probe yet), memory leaks under Instruments (its CoreDevice648plug-in is broken on this Xcode / macOS pair), Intel, multi-GPU, App Nap. Method and caveats:649[docs/PERFORMANCE.md](docs/PERFORMANCE.md).650651---652653## 📦 Release654655Distribution is **Developer ID + notarization** (the app is not sandboxed, so the Mac App Store is not an option).656657```bash658Scripts/release.sh # build Release, sign, DMG, notarize (--wait), staple659Scripts/release.sh --skip-notarize # local signed build only660```661662| Item | Value |663|---|---|664| Bundle id / version | `ai.spboucher.nexterm`, 0.1.0 (1) — `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` in `project.yml` |665| Signing | Developer ID Application, team `3YM54G49SN`, `--options runtime --timestamp`; Debug builds use Apple Development |666| Hardened Runtime | enabled in `project.yml`; entitlements in `Resources/NEXTERM.entitlements` |667| Notarization | `notarytool` with a keychain profile (`NOTARY_PROFILE`), `--wait`, then `stapler staple` on the DMG and the app |668| Outputs | `dist/NEXTERM.app` (signed, stapled), `dist/NEXTERM-<version>.dmg` (signed, notarized, stapled), `dist/notarize.log` |669670Pipeline steps: Release build → sign nested code, then the app → `codesign --verify` and `spctl` → DMG with an671`/Applications` link → sign the DMG → notarize → staple → final `spctl` check.672673Verification after the pipeline:674675```bash676codesign --verify --deep --strict --verbose=2 dist/NEXTERM.app677spctl -a -vv -t exec dist/NEXTERM.app # "accepted … source=Notarized Developer ID"678xcrun stapler validate dist/NEXTERM-*.dmg679```680681**Bumping a version**: edit `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` in `project.yml`, run682`Scripts/build.sh generate`, then `Scripts/release.sh`.683684**First-run notes for users**685686- macOS asks for Accessibility only if you use the System Events smoke test; the app itself needs no special687 permission.688- Privacy prompts (Desktop / Documents / Downloads) appear when a shell in NEXTERM touches those folders — same as689 Terminal.app.690- Notification permission is requested the first time a Claude hook event needs attention (only if hooks are enabled).691692---693694## 🩺 Troubleshooting and gotchas695696- **`xcodebuild` refuses the SwiftTerm plugin** → pass `-skipPackagePluginValidation` (`Scripts/build.sh` does); in the697 Xcode IDE, trust the plugin once.698- **App launches with no visible window** → this was `ProcessInfo.hostName` blocking the main thread on reverse DNS;699 the code uses `gethostname`. Keep it that way.700- **Empty panes after a reparent** → SwiftTerm only recomputes its grid when its frame changes while it is in a701 window; `TerminalContainerView` forces a resync when it moves to a window or superview.702- **XCUITest "Timed out while enabling automation mode"** on Xcode 27.2 + macOS 27.0 → use `Scripts/smoke-test.sh`703 (System Events) instead.704- **Xcode prints CoreDevice / CoreSimulator plug-in errors** on macOS 27.0 → noise only for a macOS app; the build705 helper filters it.706- **Custom shortcuts do not apply immediately** → they take effect at the next launch.707- **Claude sessions keep the hooks file path after hooks are turned off** → sessions already running keep it on their708 command line until restarted.709- **Claude Code's "trust this folder" prompt** appears for untrusted directories; NEXTERM never answers it.710- **libghostty** was evaluated and deferred: the build reached 320 / 337 steps, then needed the Metal Toolchain711 component, and its C API is marked unstable. The engine sits behind `TerminalCore.NEXTerminalView` /712 `TerminalSession`, so it remains a replaceable implementation detail713 ([ADR 0001](docs/ADR/0001-terminal-engine.md)).714715---716717## 🚧 Status and known limitations718719Phases 0–4 are implemented and verified on the build machine, and the Release pipeline produced a signed, notarized720and stapled 0.1.0 build; see [docs/PROGRESS.md](docs/PROGRESS.md) for the acceptance matrix.721722- **XCUITest runner blocked** by the Xcode 27.2 / macOS 27.0 combination — the UI test target exists but cannot run.723- **Multi-monitor presets** (laptop / dual / triple layouts), workspace switcher templates: not yet implemented.724- **Display hot-plug**: relocation of a window whose display is missing is unit-tested with simulated topologies; no725 physical unplug was performed.726- **Custom keybindings** need a relaunch.727- **Apple Silicon only** (`ARCHS: arm64`); Intel is neither built nor tested.728- **Input latency and leak profiling** are not instrumented.729730---731732## 👤 Author733734<div align="center">735<img src="docs/brand/icon.png" width="64" height="64" alt="">736<br>737738**Simon-Pierre Boucher** — design, development, operations739<br>740[www.spboucher.ai](https://www.spboucher.ai) · [git.spboucher.ai](https://git.spboucher.ai) · contact@spboucher.ai741742</div>743744---745746## 📄 License747748Private software. All rights reserved © 2026 Simon-Pierre Boucher.749750Third-party: [SwiftTerm](https://github.com/migueldeicaza/SwiftTerm) is distributed under the MIT license.751