SPB Git

Repository Public

README.md 42.0 KB 751 lines markdown

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)**1415![version](https://img.shields.io/badge/version-0.1.0%20%281%29-blue?style=for-the-badge)16![platform](https://img.shields.io/badge/platform-macOS%2015%2B%20%C2%B7%20Apple%20Silicon-000000?style=for-the-badge&logo=apple&logoColor=white)17![distribution](https://img.shields.io/badge/distribution-Developer%20ID%20%C2%B7%20notarized-34C759?style=for-the-badge)18![license](https://img.shields.io/badge/license-all%20rights%20reserved-lightgrey?style=for-the-badge)19![author](https://img.shields.io/badge/author-Simon--Pierre%20Boucher-0A66C2?style=for-the-badge)2021![Swift](https://img.shields.io/badge/Swift-6.0%20%C2%B7%20strict%20concurrency-F05138?style=flat-square&logo=swift&logoColor=white)22![SwiftUI](https://img.shields.io/badge/SwiftUI-%2B%20AppKit-0D96F6?style=flat-square&logo=swift&logoColor=white)23![SwiftTerm](https://img.shields.io/badge/SwiftTerm-1.99.2%20%C2%B7%20MIT-7AA2F7?style=flat-square)24![SQLite](https://img.shields.io/badge/SQLite-WAL%20%C2%B7%20schema%20v1-003B57?style=flat-square&logo=sqlite&logoColor=white)25![Network.framework](https://img.shields.io/badge/Network.framework-loopback%20hook%20receiver-555555?style=flat-square)26![OpenSSH](https://img.shields.io/badge/OpenSSH-StrictHostKeyChecking%3Dask-231F20?style=flat-square&logo=openssh&logoColor=white)27![Git](https://img.shields.io/badge/Git-CLI%20as%20source%20of%20truth-F05032?style=flat-square&logo=git&logoColor=white)28![tmux](https://img.shields.io/badge/tmux-optional%20reattach-1BB91F?style=flat-square&logo=tmux&logoColor=white)29![Claude Code](https://img.shields.io/badge/Claude%20Code-CLI%202.1.316%20verified-D97757?style=flat-square&logo=claude&logoColor=white)30![XcodeGen](https://img.shields.io/badge/XcodeGen-project.yml-1575F9?style=flat-square&logo=xcode&logoColor=white)31![Xcode](https://img.shields.io/badge/Xcode-27.2-1575F9?style=flat-square&logo=xcode&logoColor=white)32![Swift Package](https://img.shields.io/badge/Swift%20Package-NEXTERMKit%20%C2%B7%206%20modules-F05138?style=flat-square&logo=swift&logoColor=white)3334[![commits](https://git.spboucher.ai/badge/nexterm/commits.svg?style=flat-square)](https://git.spboucher.ai/nexterm/commits)35[![last commit](https://git.spboucher.ai/badge/nexterm/last-commit.svg?style=flat-square)](https://git.spboucher.ai/nexterm/commits)36[![activity](https://git.spboucher.ai/badge/nexterm/activity.svg?style=flat-square)](https://git.spboucher.ai/nexterm/insights)37[![language](https://git.spboucher.ai/badge/nexterm/language.svg?style=flat-square)](https://git.spboucher.ai/nexterm)38[![languages](https://git.spboucher.ai/badge/nexterm/languages.svg?style=flat-square)](https://git.spboucher.ai/nexterm/insights)39[![size](https://git.spboucher.ai/badge/nexterm/size.svg?style=flat-square)](https://git.spboucher.ai/nexterm)40[![branches](https://git.spboucher.ai/badge/nexterm/branches.svg?style=flat-square)](https://git.spboucher.ai/nexterm/branches)41[![tags](https://git.spboucher.ai/badge/nexterm/tags.svg?style=flat-square)](https://git.spboucher.ai/nexterm/tags)42[![clones](https://git.spboucher.ai/badge/nexterm/clones.svg?style=flat-square)](https://git.spboucher.ai/nexterm)4344![Swift files](https://img.shields.io/badge/Swift%20files-62-informational?style=flat-square)45![Swift lines](https://img.shields.io/badge/Swift%20lines-6%20764-informational?style=flat-square)46![package modules](https://img.shields.io/badge/package%20modules-6-blue?style=flat-square)47![SQLite tables](https://img.shields.io/badge/SQLite%20tables-9-blue?style=flat-square)48![themes](https://img.shields.io/badge/built--in%20themes-4-blue?style=flat-square)49![session kinds](https://img.shields.io/badge/session%20kinds-5-blue?style=flat-square)50![kit tests](https://img.shields.io/badge/kit%20tests-42-brightgreen?style=flat-square)51![app unit tests](https://img.shields.io/badge/app%20unit%20tests-9-brightgreen?style=flat-square)52![acceptance tests](https://img.shields.io/badge/acceptance%20tests-12%20%C2%B7%20see%20matrix-brightgreen?style=flat-square)53![ADRs](https://img.shields.io/badge/ADRs-2-informational?style=flat-square)5455![bundle](https://img.shields.io/badge/bundle-ai.spboucher.nexterm-555555?style=flat-square&logo=apple&logoColor=white)56![hardened runtime](https://img.shields.io/badge/Hardened%20Runtime-on-34C759?style=flat-square)57![sandbox](https://img.shields.io/badge/App%20Sandbox-off%20%28spawns%20shells%29-lightgrey?style=flat-square)58![launch](https://img.shields.io/badge/launch%20%E2%86%92%20first%20window-350%20ms-informational?style=flat-square)59![memory](https://img.shields.io/badge/32%20sessions-132%20MB%20RSS-informational?style=flat-square)60![throughput](https://img.shields.io/badge/sustained%20output-40%20MB%2Fs-informational?style=flat-square)61![telemetry](https://img.shields.io/badge/telemetry-none-success?style=flat-square)6263</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
Files main
Menu

Theme