SP Term
A native macOS terminal built for several displays, several windows and many panes — with SSH profiles, git context and an optional, bring-your-own-key assistant that never acts without you.
Author: Simon-Pierre Boucher
Table of contents
- Overview
- Install
- Features
- Shortcuts
- Screenshots
- Architecture
- Stack
- Repository layout
- Build from source
- Configuration and data
- Security and privacy
- Testing
- Benchmarks
- Release
- Brand
- Limitations and known issues
- Third-party components
- Author
- License
🎯 Overview
A native macOS terminal built for several displays, several windows and many panes — with SSH profiles, git context and an optional, bring-your-own-key assistant that never acts without you.
Swift 6 · SwiftUI + AppKit · macOS 14 or later · Apple Silicon and Intel (universal build).
Status of every feature — what is tested, what is only implemented, what is missing — is in IMPLEMENTATION_STATUS.md. Test evidence: TEST_REPORT.md. Measurements: BENCHMARKS.md.
| Version | 1.0.0 (1), built 2026-11-17 on macOS 27.0 / Xcode 27.2 |
| System | macOS 14 or later (the app relies on the Observation framework and on SwiftUI APIs introduced in macOS 14) |
| Distribution | outside the Mac App Store: Developer ID signature, hardened runtime, notarized and stapled (app and DMG) |
| Terminal engine | SwiftTerm 1.99.2 (MIT), integrated and pinned, not rewritten |
| Interface language | English only |
SP Term is a standalone project of the spboucher.ai application family: it has no backend and no sister repository. Documentation map:
| Document | Content |
|---|---|
| ARCHITECTURE.md | modules, engine choice, PTY lifecycle, workspace model, displays, storage, concurrency |
| IMPLEMENTATION_STATUS.md | state of every feature: Tested / Implemented / Partial / Not done |
| TEST_REPORT.md | suites, what each one proves, defects found, what was not tested |
| BENCHMARKS.md | launch time, memory, throughput, latency, with their method |
| RELEASE.md | release procedure, verification, state of the 1.0.0 release |
| docs/SECURITY.md | distribution model, untrusted output, paste, broadcast, SSH, assistant, data at rest |
| docs/LICENSES.md | third-party components |
| docs/RELEASE_NOTES.md | release notes |
| Assets/Brand/BRAND.md | mark, colour, typography, do / don't |
📦 Install
Open the disk image from dist/, drag SP Term to Applications, launch it.
The 1.0.0 disk image is SPTerm-1.0.0.dmg (8.3 MB), SHA-256
9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00. dist/ is a build output and is not versioned in
this repository.
Run an isolated instance (own data folder, nothing restored):
open "SP Term.app" --args -SPTermDataDir /tmp/spterm -SPTermFresh 1✨ Features
Terminal. Real PTY sessions (zsh, bash, fish or any installed shell), login shells, TERM=xterm-256color,
true colour, alternate screen, mouse reporting, bracketed paste, OSC 8 links, wide and combined characters,
bounded scrollback with regex search, drag-and-drop of files (paths are shell-escaped). Emulation is provided
by SwiftTerm (MIT).
Panes, tabs, windows. Recursive horizontal/vertical splits, mouse and keyboard resizing, keyboard focus navigation, temporary zoom, drag a pane by its header to rearrange or to another tab, move a pane or a tab to its own window and merge windows back — processes keep running throughout.
Displays. New windows open on the display you choose, windows can be sent to another display, layouts are saved with their display and restored on the displays available; when a display is unplugged its windows come back on screen. Presets: Code + Tests + Logs, SSH Fleet, Agent Command Center, 4 Panes, Dual Monitor, and 2/3/6/8-pane grids.
Workspaces. The arrangement is restored at launch — layout, titles, session types and directories. Processes are started fresh and SP Term says so; for sessions that survive a restart, use the built-in tmux/zellij entries of the Command Palette (shown when those tools are installed).
SSH. Hosts from ~/.ssh/config and profiles you add, groups and favourites, ProxyJump, one-click sessions
or a grid of hosts. SP Term runs the system OpenSSH: keys stay in your agent, passwords are typed in the
terminal and never stored, host keys are always verified by OpenSSH.
Git context. Branch, ahead/behind, staged/changed/untracked files, diffs and recent commits for the focused session — strictly read-only.
SP Intelligence (optional, off by default). Explain output, suggest or draft commands, review a diff, with Anthropic, OpenAI or a local OpenAI-compatible server. You pick what text is attached, you see the exact payload before it is sent, secrets are masked, a local-only mode refuses anything but this Mac, and no suggested command runs without your confirmation (a typed phrase for destructive ones). Installed agent CLIs such as Claude Code can be opened in their own panes, with their own authentication.
Also. Command palette, customizable shortcuts, snippets with variables, quick terminal on a global hotkey, session export with secret masking, themes (dark, light, high contrast), opacity and blur, focus and presentation modes, per-task CPU/memory in the status bar, optional notifications.
The nine layout presets (Packages/SPTermKit/Sources/WorkspaceKit/Presets.swift)
| Preset | Description |
|---|---|
| Code + Tests + Logs | a large editor pane with tests and logs stacked on the right |
| SSH Fleet | a grid with one pane per selected host |
| Agent Command Center | one supervisor shell and a column of agent panes, each with its own PTY |
| 4 Panes | a 2 × 2 grid of shells |
| Dual Monitor | one window per display: work on the primary, monitoring on the second |
| 2 Panes · 3 Panes · 6 Panes · 8 Panes | grids |
Feature status at a glance (summary of IMPLEMENTATION_STATUS.md)
Legend — Tested: covered by an automated test or an observed end-to-end check · Implemented: code in place and compiling, behaviour not verified beyond what is stated · Partial / Not done: as described. Nothing is marked Tested on the basis of "it should work".
| Area | Tested | Implemented, not verified live | Partial / not done |
|---|---|---|---|
| Terminal core | real PTY, job control, signals, resize, no descriptor leak, engine conformance (15 tests, malformed corpus, 60 fuzz rounds), vim / less / top / python / ssh, scrollback and search | fish and other shells, selection and ⌘-click, drop gesture, Metal renderer (off by default) | ligatures follow the font (no switch); line spacing fixed by the engine; inline images not validated; nvim / htop / nano not verified |
| Windows, panes, displays | tabs, recursive splits (incl. 200 random operation sequences), keyboard resize and focus, zoom, detach / merge keeping the shell alive, presets, broadcast guards, native full screen | divider drag, tab reorder by drag | multi-display on simulated displays only; Spaces not specifically handled; pane count hint only |
| Sessions and workspaces | new / duplicate / rename / restart, layout autosave and restore, versioned storage with migration v1→v2 and corruption recovery, private mode, opt-in history | quit confirmation when busy | tmux / zellij: palette entries only; per-directory profiles not done |
| SSH, git, tools | ~/.ssh/config parsing, command builder rules, hostile names refused, one live session to a LAN host, failure diagnosis and reconnect, read-only git, snippets, Finder "open with" |
known_hosts in the dashboard, resource monitor, notifications, quick terminal, Finder Services entry | SFTP opens the system sftp in a tab; SSH latency not done; no automatic updates |
| SP Intelligence | preview before send, secret masking (28 cases), local-only mode, consent gate, 118 risk-analyzer cases, Keychain round trip — with a mock transport: no request was ever sent to a real provider | the five modes (answer quality not evaluated), agent CLIs in panes | streaming exists in the client; the panel uses non-streaming requests |
| Interface | command palette, themes (contrast ratios asserted), font 6–72 pt, shortcut model | opacity and blur, focus and presentation modes | VoiceOver not audited; no localization |
⌨️ Shortcuts
Defaults — all editable in Settings › Shortcuts.
| New window | ⌘N | New tab | ⌘T |
| Split right / down | ⌘D / ⇧⌘D | Close pane / tab / window | ⌘W / ⌥⌘W / ⇧⌘W |
| Focus pane | ⌥⌘ arrows | Next / previous pane | ⌘] / ⌘[ |
| Resize pane | ⌃⌘ arrows | Zoom pane | ⇧⌘↩ |
| Next / previous tab | ⇧⌘] / ⇧⌘[ | Tab 1–9 | ⌘1 … ⌘9 |
| Command palette | ⇧⌘P | Find / next / previous | ⌘F / ⌘G / ⇧⌘G |
| Sidebar | ⌥⌘S | SSH hosts | ⇧⌘H |
| Snippets | ⇧⌘S | Git context | ⌥⌘G |
| SP Intelligence | ⇧⌘A | Broadcast input | ⌥⌘I |
| Move window to next display | ⌃⌥⌘→ | Save workspace | ⌘S |
| Text size | ⌘= / ⌘- / ⌘0 | Clear scrollback | ⌘K |
| Focus mode | ⌃⌘M | Full screen | ⌃⌘F |
| Restart session | ⇧⌘R | Quick terminal (when enabled) | ⌃⌥` |
🖼 Screenshots
Evidence captured from the running app during testing (docs/evidence/, 8 files).
![]() First launch |
![]() Three panes |
![]() vim in a pane |
![]() Command palette |
![]() Dark theme |
![]() Sidebar and git context |
![]() Assistant, off by default |
![]() Restored workspace |
🏗 Architecture
Swift 6 (strict concurrency), SwiftUI for the chrome, AppKit for windows, focus, menus, screens and the terminal view. Full text: ARCHITECTURE.md.
flowchart TB
APP["SP Term.app<br/>App/Sources/SPTerm — AppKit lifecycle, SwiftUI views<br/>AppModel · WorkspaceWindowController · panels"]
subgraph KIT["Packages/SPTermKit — core"]
PTY["PTYProcess<br/>forkpty → posix_spawn SETEXEC"]
CORE["TerminalCore<br/>session = PTY + emulator view<br/>paste / broadcast guards"]
WS["WorkspaceKit<br/>recursive split tree, tabs, windows, presets"]
WM["WindowManager<br/>placement on displays, rescue, tiling"]
STORE["SessionStore<br/>versioned JSON, migrations, recovery"]
SET["SettingsModel<br/>preferences, key chords"]
DS["DesignSystem<br/>themes, contrast maths"]
end
subgraph REMOTE["Packages/SPRemoteKit"]
SSH["SSHKit<br/>ssh config parser, argv builder,<br/>known_hosts inspector, error classifier"]
GIT["GitKit<br/>read-only git context"]
PROC["SPProcess (internal)<br/>bounded, time-limited subprocesses"]
end
subgraph AI["Packages/SPIntelligence"]
ASSIST["AIAssistant<br/>BYOK clients, Keychain store, secret redactor,<br/>risk analyzer, consent gate, network policy"]
end
ST["SwiftTerm 1.99.2<br/>VT/xterm parser + renderer (MIT, pinned)"]
APP --> CORE & WS & WM & STORE & SET & DS & PTY
APP --> SSH & GIT
APP --> ASSIST
CORE --> PTY & DS & SET
CORE --> ST
WM --> WS
STORE --> WS & SET
SET --> DS
SSH --> PROC
GIT --> PROC
SSH -. "argv only" .-> OSSH["/usr/bin/ssh · /usr/bin/sftp"]
GIT -. "allow-listed subcommands" .-> OGIT["/usr/bin/git"]
Dependency rule: models (WorkspaceKit, WindowManager, SettingsModel, DesignSystem) import no UI framework
beyond CoreGraphics types and never touch NSScreen/NSWindow, which is what lets the multi-monitor logic be tested
with simulated displays. The app reads NSScreen in exactly one place (ScreenReader).
Engine choice
| Option | Decision |
|---|---|
| Write a VT/xterm emulator from scratch | Rejected: a correct emulator (alternate screen, scroll regions, wide/combining text, mouse modes, bracketed paste, OSC 8/52, reflow…) is years of work; claiming one after a short build would be dishonest. |
| libghostty | Not used: no stable public embedding API at the time of writing; building it needs the Zig toolchain and a Metal toolchain component that was missing when it was evaluated. |
| SwiftTerm 1.99.2 | Chosen. MIT licence, pure Swift, actively maintained, native NSView, thread-safe feed, built-in search, accessibility service, optional Metal renderer. Pinned to an exact version. |
What is home-made on top of the engine: the PTY layer, the session object, launch planning, paste and broadcast
guards, the whole window/tab/pane/workspace system, persistence, SSH/Git/AI modules and the UI. ConformanceTests
pin the engine behaviours SP Term depends on (15 tests including malformed input and fuzzing).
PTY and process lifecycle
sequenceDiagram autonumber participant S as TerminalSession (main actor) participant P as PTYProcess (one serial queue) participant C as Child process participant E as SwiftTerm engine S->>P: init(program, argv, env, cwd, size) P->>C: forkpty(termios IUTF8, winsize) — new session + controlling terminal on fds 0/1/2 C->>C: posix_spawn(SETEXEC, CLOEXEC_DEFAULT, SETSIGDEF, SETSIGMASK, chdir) Note over C: the program replaces the child and inherits no descriptor of the app C-->>P: output on the master (O_NONBLOCK, read source) P-->>E: bytes fed straight from the PTY queue (thread-safe feed) S->>P: write(keys) — pending buffer, never blocks the UI S->>P: resize → TIOCSWINSZ (kernel raises SIGWINCH) C-->>P: exit → waitpid → drain remaining output P-->>S: onExit(status) — output always before exit
- Only async-signal-safe calls happen between
forkptyand exec; argv/envp/attributes are built before. On failure errno is written to a close-on-exec pipe and the launch throws. terminate=SIGHUPto the session, thenSIGKILLafter a grace period;deinithangs up and reaps, so no zombie and no orphan survives.- Foreground job detection uses
tcgetpgrpon the master; cwd/CPU/memory come fromlibproc. - An earlier design used
posix_spawnalone withPOSIX_SPAWN_SETSID. Tests showed that on macOS the slave is then not acquired as controlling terminal (zsh lost job control), henceforkpty.
Session, workspace model, displays
- Session (
TerminalCore.TerminalSession,@MainActor @Observable) owns oneSPTerminalView(aSwiftTerm.TerminalViewsubclass) and onePTYProcess. Byte counters are sampled once per second on the main actor, so heavy output never floods the main thread with observation updates. A session is independent from windows: moving a pane only re-parents its view. UserInputScopemarks key-event dispatch, pastes and drops; only bytes sent inside that scope are offered to broadcast input, so automatic terminal replies are never mirrored.LayoutNodeis an n-ary split tree (value type):.pane(id)or.split(axis, fractions, children), always normalized (no single-child split, no nested split of the same axis, fractions sum to 1). Operations: split, remove, swap, move-to-edge, divider resize, keyboard resize, equalize, geometric neighbour lookup, frames/dividers for a rectangle, grid builders.PlacementEngineguarantees that every frame it returns is reachable (title bar inside the visible area of an existing display).resolverestores a saved window (same display → kept; another resolution → rescaled; display id changed → matched by name + size; display gone → moved to the main display keeping proportions).rescueis called ondidChangeScreenParametersNotificationand moves only windows that became unreachable.AppModel(main actor, observable) owns sessions ([PaneID: TerminalSession]), window states and all operations.
Concurrency
Swift 6 language mode with complete checking in every target. UI state is @MainActor. PTYProcess confines its
mutable state to one serial queue (@unchecked Sendable, documented). Git and AI calls are async; AI requests can
only be built from an ApprovedPreview, commands can only run from an ApprovedCommand — both types have no public
initializer.
Assistant consent flow
sequenceDiagram autonumber participant U as User participant A as Assistant panel participant R as SecretRedactor participant G as ConsentGate participant P as Provider (BYOK) U->>A: question (+ optional "Selected text" or "Last 60 lines") A->>R: mask secrets R-->>A: ContextPreview — destination, model, byte count, masked text A-->>U: exact payload shown U->>A: Send A->>P: AIClient.send(ApprovedPreview) P-->>A: answer with suggested command (text only) U->>A: Review & Run A->>G: full command, target, host, directory, risk reasons G-->>U: confirmation (typed phrase when destructive, sudo, network transfer or multi-host) U->>G: confirm G-->>A: ApprovedCommand → typed into the session
🧱 Stack
| Layer | Technology | Version | Role |
|---|---|---|---|
| Language | Swift | language mode 6.0, SWIFT_STRICT_CONCURRENCY: complete (project.yml) |
everything |
| UI | SwiftUI + AppKit | system | chrome · windows, focus, menus, screens, terminal view |
| Project | XcodeGen (project.yml) → SPTerm.xcodeproj |
xcodeVersion: 27.2 |
targets SPTerm and SPTermTests |
| Packages | SwiftPM, swift-tools 6.0, platform macOS 14 | 3 local packages | SPTermKit (7 libraries), SPRemoteKit (2 libraries + internal SPProcess), SPIntelligence (1 library) |
| Terminal engine | SwiftTerm | 1.99.2, exact pin, MIT | VT/xterm parser, buffer, renderer, search, accessibility |
| SSH | system OpenSSH (/usr/bin/ssh, /usr/bin/sftp, /usr/bin/ssh-keygen) |
system | SP Term builds an argument vector, no crypto of its own |
| Git | system /usr/bin/git |
system | read-only, allow-listed subcommands |
| Assistant | Anthropic, OpenAI, OpenAI-compatible HTTP APIs | bring your own key | optional, off by default |
| Secrets | macOS Keychain (service ai.spboucher.spterm.ai) |
system | API keys only |
| Process probes | libproc, tcgetpgrp |
system | cwd, CPU, memory, foreground job |
| Tests | Swift Testing (packages) · XCTest hosted in the app · System Events smoke script | Xcode 27.2, Swift 6.4.2 in the test report | 257 automated tests + 29 end-to-end checks |
🗂 Repository layout
155 tracked files; 79 Swift files, 16 549 lines (tests included).
App/
Sources/SPTerm/ 19 files — application target
App/ AppDelegate, Actions, SearchSupport
Model/ AppModel, WindowState
Panels/ AssistantPanel, GitPanel, HostsAndSnippets
Views/ WindowRootView, PaneViews, SidebarView, CommandPaletteView, SettingsView, Sheets, Styling, SPColor
Windows/ WorkspaceWindowController, QuickTerminalController, Notifier
Tests/SPTermTests/ hosted integration tests (WorkspaceTests, SafetyTests, PerformanceTests, Support)
Packages/
SPTermKit/ PTYProcess · TerminalCore · WorkspaceKit · WindowManager · SessionStore · SettingsModel · DesignSystem (+ 6 test targets)
SPRemoteKit/ SSHKit · GitKit · SPProcess (+ 2 test targets)
SPIntelligence/ AIAssistant (+ 1 test target)
Assets/Brand/ icon sources (SVG), three concepts, PNG exports 1024–16 px, brand guide, render.sh
Resources/ Info.plist, SPTerm.entitlements, Assets.xcassets (AppIcon, AccentColor)
Scripts/ build, kit, smoke, drive, bench, release, notarize, window-shot
docs/ SECURITY.md, LICENSES.md, RELEASE_NOTES.md, evidence/ (8 screenshots), brand/ (logo, icon)
ARCHITECTURE.md · IMPLEMENTATION_STATUS.md · TEST_REPORT.md · BENCHMARKS.md · RELEASE.md
project.yml XcodeGen definition🛠 Build from source
You need Xcode 27 and XcodeGen.
Scripts/build.sh generate # creates SPTerm.xcodeproj from project.yml
Scripts/build.sh run # debug build + launch
Scripts/build.sh kits # unit tests of the three Swift packages
Scripts/build.sh test # integration tests hosted in the app| Script | Purpose |
|---|---|
Scripts/build.sh |
build helper: generate, debug, release, run, kits, test, app-path (filters the Xcode 27.2 plug-in noise that is irrelevant to a macOS app) |
Scripts/kit.sh |
builds / tests one local package and prints only the useful diagnostics: Scripts/kit.sh test SPTermKit --filter Name |
Scripts/smoke.sh |
end-to-end smoke test of the real application, driven through System Events; every check is observed outside the app |
Scripts/drive.sh |
sends keystrokes to the running app through System Events (used by the smoke tests) |
Scripts/bench.sh |
launch time (5 launches after one warm-up) and memory of a built app |
Scripts/release.sh |
universal Release build, Developer ID signature, hardened runtime, verification → dist/SP Term.app |
Scripts/notarize.sh |
notarizes and staples the app, then builds, signs, notarizes and staples the DMG and writes its SHA-256 |
Scripts/window-shot.swift |
captures the frontmost window of a named app to a PNG |
Assets/Brand/render.sh |
regenerates every icon PNG and the AppIcon.appiconset (needs rsvg-convert) |
⚙️ Configuration and data
| Setting | Value | Where |
|---|---|---|
| Bundle identifier | ai.spboucher.spterm (tests: ai.spboucher.spterm.tests) |
project.yml |
| Team | 3YM54G49SN |
project.yml |
| Version | MARKETING_VERSION 1.0.0 · CURRENT_PROJECT_VERSION 1 |
project.yml |
| Deployment target | macOS 14.0 | project.yml |
| Architectures | Debug: arm64 · Release: arm64 x86_64 |
project.yml |
| Category | public.app-category.developer-tools |
Resources/Info.plist |
| Finder integration | opens folders (public.folder, alternate handler); Services entry "New SP Term Window Here" |
Resources/Info.plist |
| Launch arguments | -SPTermDataDir <dir> (own data folder) · -SPTermFresh 1 (nothing restored) |
App/Sources/SPTerm/App/AppDelegate.swift |
| Notarization profile | NOTARY_PROFILE environment variable, default MacLustr-Notarize (a notarytool keychain profile, referred to by name only) |
Scripts/notarize.sh |
Data directory ~/Library/Application Support/SP Term/ (0700), files 0600, each a versioned envelope
{"schemaVersion": N, "payload": …} written atomically (temp file + rename):
| File | Content |
|---|---|
settings.json |
preferences and shortcut overrides |
last-session.json |
layout autosaved while running (schema 2; schema 1 is migrated) |
workspaces.json |
named workspaces |
snippets.json |
command snippets |
hosts.json |
SSH profiles added in the app (no secrets) |
ai-providers.json |
provider label, URL, model — never the key |
history.jsonl |
opt-in command history (snippets / assistant / broadcast only) |
An unreadable or newer-schema file is renamed *.unreadable-<timestamp> and defaults are used; a damaged layout is
repaired tab by tab. API keys are in the Keychain. Terminal output is never written to disk unless the user exports a
session.
🛡 Security and privacy
In short (details: docs/SECURITY.md):
- Distributed outside the Mac App Store with a Developer ID signature and the hardened runtime; not sandboxed (a terminal must run arbitrary programs with your permissions). One entitlement only: Apple Events automation for programs you run.
- Nothing about your sessions leaves the Mac unless you press Send in the assistant after reviewing the payload.
- No terminal output is written to disk unless you export it. Private mode disables layout saving, history and notifications.
- Pastes with several lines ask first; pastes containing escape sequences always ask. Programs cannot read the clipboard (OSC 52) unless you allow it, and writing it asks by default.
- Broadcast input is off at every launch, needs a confirmation, shows a permanent banner and holds destructive lines.
- API keys live in the macOS Keychain. SSH keys and passwords are never read, copied or stored.
| Mechanism | State |
|---|---|
| Hardened runtime | On. No allow-jit, no allow-unsigned-executable-memory, no disable-library-validation, no get-task-allow, no debugger entitlement |
| Entitlements | Exactly one: com.apple.security.automation.apple-events, so that programs the user runs (e.g. osascript) can send Apple Events — each target still requires the user's consent in a system prompt |
| TCC (privacy prompts) | Not bypassed. When a program in a session touches Desktop / Documents / Downloads, the local network, etc., macOS asks on behalf of SP Term; the usage strings explain that a program in a session triggered it |
| Privileges | The app never asks for root, installs no helper, no launch agent, no kernel / system extension, and never touches SIP or Gatekeeper settings |
| Child processes | Inherit no file descriptor of the app (tested), get default signal handling and a cleaned environment (DYLD_*, XPC_* and debugging variables are stripped) |
Untrusted terminal output
- Escape sequences: parsed by the engine; malformed / unknown sequences are ignored (conformance + fuzz tests).
- Window title (OSC 0/2): control characters removed, length capped.
- Clipboard (OSC 52): write is
askby default (the text and the requesting program are shown), read isdenyby default. Both are settings. - Links (OSC 8 and detected URLs):
http,https,mailtoopen directly on ⌘-click;file:is only revealed in Finder, never launched;javascript:/data:are blocked; any other scheme asks first. - Notifications: only process name and duration are shown, never terminal text.
Paste, broadcast, SSH
- Several lines → confirmation with a preview where control characters are made visible (configurable). Text containing escape sequences or the bracketed-paste terminator → always asks, and the default action pastes a sanitized version. Sanitized pastes never end with a line break, so nothing runs before the user presses Return.
- Dropped files insert shell-escaped paths (round-trip tested against a real shell with 17 hostile names).
- Broadcast: off at every launch (never persisted); enabling it shows which sessions will receive input and requires a
confirmation; a full-width banner and coloured pane borders stay visible; lines that look destructive or use
sudoare held for the other panes until the user types the confirmation phrase. Limit: the pane being typed in is a normal terminal — the line runs there as typed; the guard protects the fan-out. - SSH: every field is validated against an allow-list (no leading
-, no whitespace, no shell metacharacters); the builder never emitsStrictHostKeyChecking,UserKnownHostsFile,BatchModeor password options; extra-ooptions go through an allow-list. Host key verification is OpenSSH's interactive prompt in the terminal; SP Term never answers it. Opening a host runssshonly — no command is sent to remote hosts.
Assistant guarantees, enforced by types and tests
- No request without a preview:
AIClient.sendonly accepts anApprovedPreview, which can only be made from aContextPreviewthe user has seen. - The preview is the exact payload (destination, model, byte count, masked text). Secrets are always masked first.
- Terminal text is attached only when the user selects Selected text or Last 60 lines.
- Local-only mode refuses every non-loopback destination before any I/O; plain HTTP to a remote host is refused.
- API keys are stored in the Keychain, sent in a header, and wrapped in a type whose description is redacted.
- Suggested commands are text. Insert types them without Return. Review & Run goes through the consent gate: full command, target, host, directory, risk reasons; destructive, sudo, network-transfer and multi-host commands need a typed phrase.
Not stored: terminal output, keystrokes typed at prompts, API keys, SSH credentials. There is no plugin system and no scripting bridge: SP Term loads no third-party code and exposes no automation interface that could run commands.
Known limits: the risk analyzer and the secret redactor are pattern based — safe means "no known risky pattern",
and an unusual secret format can pass unmasked (the preview exists so the user can check). A program running in a
session has the user's full permissions; SP Term does not confine it. Exported session files contain whatever was on
screen (masked by default); they are created 0600.
✅ Testing
Report: TEST_REPORT.md — 2026-11-17, MacBook Pro Apple M5 Max, macOS 27.0, Xcode 27.2, Swift 6.4.2, one display. All numbers are copied from the output of the listed commands.
| Suite | Command | Result |
|---|---|---|
| SPTermKit (core) | Scripts/kit.sh test SPTermKit |
98 tests passed (PTY 17, terminal core 34, workspace 19, placement 13, storage 10, themes 5) |
| SPRemoteKit | Scripts/kit.sh test SPRemoteKit |
65 tests passed (SSH 39, git 26) |
| SPIntelligence | Scripts/kit.sh test SPIntelligence |
56 tests passed (parameterized: 118 risk cases, 28 redaction cases, 27 loopback hosts) |
| App integration (hosted in the app) | Scripts/build.sh test |
38 tests passed (workspace 8, displays 6, broadcast 3, paste/clipboard 5, assistant 6, remote/registry 7, performance 3) |
| End-to-end on the running app | Scripts/smoke.sh |
29 checks; six runs, from 23 to 29 passed; last run on the signed Release build: 29/29 |
| Total automated tests | 257 unit / integration tests, 0 failing at the last run |
What each suite proves
- PTY (real processes) — output and exit code; a real controlling terminal;
SIGWINCHdelivered with the new size; Ctrl+C interrupts the foreground job and not the shell; Ctrl+Z suspends and job control works in zsh; Ctrl+D is end-of-file; Unicode round trip (accents, CJK, ZWJ emoji); terminate ends and reaps the session; the child inherits no descriptor of the app; 200 000 lines are delivered completely before the exit is reported; 300 KB of input is accepted without blocking. - Engine conformance (SwiftTerm 1.99.2 headless) — cursor addressing, erase / insert / delete line, SGR including 256 and true colour, alternate screen, scrolling region, bracketed paste, mouse and focus-report modes, OSC 0/2/8/52, wide / combining / ZWJ / flag sequences, wrap and reflow, bounded scrollback, a corpus of malformed sequences and invalid UTF-8, 60 fuzz rounds of 4 000 random chunks with random resizes. These are checks of the integrated engine, not of an emulator written for SP Term.
- Layout and workspace model — recursive splits, exact tiling without overlap for 2/3/4/6/8 panes, divider and keyboard resizing with minimum sizes, geometric focus navigation, Codable round trip, 200 random operation sequences preserving all invariants.
- Multi-display placement (simulated monitors) — 500 random configuration changes (1–3 displays, a projector,
random frames) never leave a window unreachable; hosted versions run against real
NSWindowobjects. - Storage — 0600 / 0700 permissions, corrupt file set aside not deleted, newer schema refused and preserved, migration from schema 1, history opt-in, private mode, masking.
- SSH and git — config parsing fixtures, every command-builder security rule, hostile host names refused, read-only git on temporary repositories, the allow-list refusing mutating subcommands. One real session to a LAN host was opened by hand through the palette.
- Safety (hosted) — broadcast guards, paste policy including escape injection, OSC 52, and the assistant: no request without preview and explicit send (counted on a mock transport), masked payload, the API key never in the body or in descriptions, execution only through the consent gate.
End-to-end. XCUITest cannot be used on this toolchain (Xcode 27.2 on macOS 27.0 times out "enabling automation
mode"), so Scripts/smoke.sh drives the real app with System Events and observes results from outside (files written
by commands typed into panes, window counts, the saved layout).
Defects found by testing and fixed
| Found by | Defect | Fix |
|---|---|---|
| PTY tests (Ctrl+Z) | zsh had no controlling terminal: opening the slave after POSIX_SPAWN_SETSID does not acquire it on macOS |
launch through forkpty + exec-mode posix_spawn |
| PTY tests | exit of very short programs could be missed (process source registered after the exit) | registration handler + end-of-file triggered polling |
| PTY tests (crash, signal 5) | releasing a suspended dispatch write source | the source is cancelled and recreated instead of suspended |
| Screenshot after a split | keyboard stayed in the previous pane while the new one was highlighted | the terminal container claims first responder when its view enters the window |
| Screenshot of an ended SSH pane | status bar showed "Exited" twice and a local directory for a remote session | status bar corrected |
| Benchmark | reading the whole 200 000-line buffer in a polling loop stalled the parser (a flaw of the test, 0.4 MB/s) | completion observed through a sentinel file and the visible rows |
| Theme tests | secondary text below 4.5:1 on the two light themes | darker secondary text on light themes |
Not tested
- More than one physical display (only simulated displays were available); Spaces.
- VoiceOver; the app was not run with VoiceOver on.
- Mouse gestures: divider dragging, tab and pane drag & drop, ⌘-click on links, text selection.
- Quick terminal hotkey, notifications, the Finder Services entry, the session export save panel.
- Real AI providers (no request was sent), real agent CLIs inside panes.
- fish, nvim, htop, nano (first three not installed on the reference machine); tmux attach entry.
- Intel execution: the x86_64 slice is built and signed but was not run.
- macOS 14 and 15: the deployment target is 14.0 but the app only ran on macOS 27.0.
- Long-duration use, sleep / wake, very large numbers of sessions.
⚡ Benchmarks
Measured on 2026-11-17 on one machine (MacBook Pro, Apple M5 Max, 48 GB RAM, macOS 27.0), single runs unless a spread is given: orders of magnitude, not guarantees. Renderer under test: the engine's default CoreGraphics renderer; the Metal renderer was not measured and SP Term makes no claim of GPU acceleration. Full text: BENCHMARKS.md.
| Measure | Result | Method |
|---|---|---|
| Launch → first window on screen | 250–259 ms (median 255, 5 launches) | Scripts/bench.sh, signed universal Release build |
| Memory, 1 pane, idle | 57 MB physical footprint (100 MB resident) | footprint, ps |
| Memory, 8 panes (8 shells), idle | 64 MB footprint (107 MB resident) | preset grid8 |
| CPU, 8 idle panes | 1.2 % | ps |
| Bundle size / DMG size | 23 MB / 8.3 MB | universal binary |
Large stdout: cat of 51 MB / 400 000 lines |
0.51 s — ≈ 100 MB/s (Debug: 13.5 s) | in-process, window not on screen: excludes drawing |
| Echo latency: key → PTY → echo → screen buffer | median 0.26 ms, p95 0.36 ms (200 keys) | stops at the screen buffer |
| 300 view resizes while a loop prints | 0.32 s | setFrameSize × 300, then stty size |
| Memory with a full 200 000-line scrollback | ≈ 365 MB more | task_info before / after |
| Backward search in 200 000 lines | 2.5 s | findPrevious |
Reading these numbers: typing latency to glass was not measured (the 0.26 ms figure stops at the screen buffer); throughput is without drawing; a long scrollback is memory-hungry (roughly 1.8 KB per line at this width — the default is 20 000 lines, the setting goes up to 1 000 000); searching a 200 000-line scrollback runs on the main thread; Debug builds are 10–25 times slower on the parsing paths, always measure Release.
🚀 Release
Procedure: RELEASE.md. Prerequisites are checked, never created, by the scripts: Xcode 27, XcodeGen, a
Developer ID Application certificate in the login keychain, and a notarytool keychain profile referred to by
name only.
Scripts/build.sh kits # 1. unit tests of the three packages
Scripts/build.sh test # 2. integration tests hosted in the app
Scripts/release.sh # 3. universal Release build, Developer ID signature, hardened runtime, verification
Scripts/smoke.sh "dist/SP Term.app" # 4. end-to-end check of the signed build
Scripts/notarize.sh # 5. notarize + staple the app, build/sign/notarize/staple the DMG, SHA-256Versioning: MARKETING_VERSION and CURRENT_PROJECT_VERSION live in project.yml. Bump them, add a section to
docs/RELEASE_NOTES.md and to the changelog of RELEASE.md, then regenerate the project (Scripts/build.sh generate).
Verification of a finished release:
codesign --verify --deep --strict --verbose=2 "dist/SP Term.app"
codesign -d --entitlements - --xml "dist/SP Term.app" | plutil -p -
xcrun stapler validate "dist/SP Term.app"
xcrun stapler validate dist/SPTerm-<version>.dmg
spctl --assess --type execute --verbose=2 "dist/SP Term.app"
spctl --assess --type open --context context:primary-signature --verbose=2 dist/SPTerm-<version>.dmg
shasum -a 256 -c dist/SPTerm-<version>.dmg.sha256| State of 1.0.0 (1) | Result (from RELEASE.md) |
|---|---|
| Tag | v1.0.0 |
dist/SP Term.app |
universal (x86_64 arm64), Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), hardened runtime, one entitlement |
| Notarization | app and DMG Accepted by Apple |
| Stapling | app and DMG validated with stapler validate |
| Gatekeeper | spctl: accepted, source=Notarized Developer ID (app, DMG, app inside the mounted DMG) |
dist/SPTerm-1.0.0.dmg |
8 287 990 bytes, SHA-256 9f07160dd2f174d19a4830e90d89656a1accc28f779650a8febeda2e24eb5a00 |
| Published by the scripts | No — nothing is uploaded except to Apple's notary service; the DMG stays in dist/ |
Updates. No automatic update mechanism is enabled: there is no feed URL. Sparkle (EdDSA-signed appcasts served over HTTPS, private key kept off the repository) is the intended mechanism once a distribution URL exists.
🎨 Brand
The mark is an SP monogram drawn as a monoline, with a glowing block cursor parked under the bowl of the P:
read left to right it says SP▮. Guide: Assets/Brand/BRAND.md.
| File | Purpose |
|---|---|
Assets/Brand/SPTermIcon.svg |
master drawing, used for 64 px and above |
Assets/Brand/SPTermIcon-small.svg |
simplified drawing, used for the 16 and 32 px renders |
Assets/Brand/SPTermGlyph.svg |
single-colour template glyph (menus, toolbar, in-app) |
Assets/Brand/Concepts/ |
the three explored concepts (A is the winner, chosen on small-size legibility) |
Assets/Brand/Exports/ |
RGBA exports 1024–16 px |
docs/brand/ |
README lockup (logo.svg) and 256 px icon (icon.png) |
Brand gradient: #22D3EE → #4C8DFF → #9B6CFF (cyan at the bottom-left, violet at the top-right) on graphite surfaces
(#0D0F13 … #323844). UI font SF Pro, terminal font SF Mono (default 13 pt). The wordmark is written SP Term.
Assets/Brand/render.sh # needs rsvg-convert (brew install librsvg)🚧 Limitations and known issues
See IMPLEMENTATION_STATUS.md for the full list.
- Restored sessions are new processes; persistence across restarts relies on tmux/zellij.
- Ligatures depend on the chosen font; line spacing is not adjustable; inline images depend on the engine's default support and are not validated.
- Metal rendering is an experimental switch, not the measured default.
- Automatic updates are not included (no update feed is configured).
- Multi-display behaviour is covered by simulated-display tests; it was exercised on real hardware with one display only.
- The Intel slice of the universal binary was built and signed but never executed; macOS 14 and 15 were not run.
- No request was ever sent to a real AI provider: the assistant is tested with a mock transport.
- The interface is in English only; VoiceOver was not audited.
Known issues:
- The 16 px icon is soft (strokes are not pixel-hinted).
- During one automated run a second window opened without a traceable cause; it could not be reproduced in two replays of the same keystrokes (other automation was active on the machine at the time).
- System Events key injection is unreliable when keystrokes are sent faster than about 1 per second on the reference machine; the smoke test therefore runs slowly and can report a spurious failure.
- A 200 000-line scrollback costs several hundred MB of memory; the default is 20 000.
- Exported text keeps soft-wrapped lines as separate lines.
📚 Third-party components
| Component | Version | Licence | Use |
|---|---|---|---|
| SwiftTerm | 1.99.2 (exact pin) | MIT — © 2019-2026 Miguel de Icaza, xterm.js authors, SourceLair, Christopher Jeffrey | terminal emulation engine (parser, buffer, renderer, search, accessibility) |
| swift-argument-parser | 1.8.2 (transitive, build tools of SwiftTerm only) | Apache-2.0 | not linked into the app |
SwiftTerm is used unmodified through Swift Package Manager. SP Term subclasses its TerminalView (SPTerminalView)
to add guarded paste, file drops and a host context menu; no source of the engine is patched. The MIT notice is shown
in the About panel and reproduced in the distribution. System tools executed at the user's request, not redistributed:
/usr/bin/ssh, /usr/bin/sftp, /usr/bin/ssh-keygen, /usr/bin/git, the user's shells, and optional
tmux / zellij / agent CLIs. All colour themes, the icon and the brand assets are original to SP Term.
Details: docs/LICENSES.md.
👤 Author
Simon-Pierre Boucher — design, development, operations
📄 License
© 2026 Simon-Pierre Boucher. All rights reserved. Terminal emulation by SwiftTerm, © Miguel de Icaza and contributors (MIT).







