ADR 0001 — Terminal engine: SwiftTerm 1.99.2 (libghostty evaluated, deferred)
Status: Accepted — 2026-11-01 Deciders: NEXTERM implementation (Claude Code session on the build Mac)
Context
CLAUDE.md asks for a maintained Ghostty integration if technically and legally feasible, with a minimal proof-of-concept before committing, and otherwise a documented alternative. The P0 requirements are real PTY sessions, VT/xterm emulation (alternate screen, wide/combining chars, bracketed paste, mouse), selection, clipboard, search, scrollback, and non-blocking rendering.
Spike 1 — libghostty (ghostty-org/ghostty main, 1.4.1-dev)
- Toolchain: Ghostty
build.zig.zonrequiresminimum_zig_version = "0.17.0"; Homebrew ships zig 0.17.0, installed for the spike. - Command:
zig build -Demit-xcframework=true -Dapp-runtime=none -Doptimize=ReleaseFast - Result: 320/337 steps succeeded in 1 min 49 s, then failed at
xcrun -sdk macosx metal …/shaders.metalwitherror: cannot execute tool 'metal' due to missing Metal Toolchain; use: xcodebuild -downloadComponent MetalToolchain. Log:/tmp/nexterm-spike/ghostty-build.log(reproducible by re-running the command). - Integration assessment (from
include/ghostty.h, 330ghostty_*symbols): the C API embeds a full surface and expects the host to implement the apprt callback table (clipboard, config, actions, keyboard, mouse, rendering lifecycle). It is explicitly marked unstable by the Ghostty project and is consumed only by Ghostty's own macOS app. License: MIT. - Verdict: feasible but expensive — a multi-day integration on an unstable API, plus a Zig toolchain and the Metal Toolchain component as build prerequisites for every contributor.
Spike 2 — SwiftTerm v1.99.2 (migueldeicaza/SwiftTerm)
- License: MIT. Maintenance: last push 2026-11-01 (the day of the spike); 1.7k stars.
- Swift package with
swiftLanguageModes: [.v6], macOS 11+, SPM-native; renders through Metal (shaders embedded as source, so no Metal Toolchain needed — verified inApple/Metal/MetalShaderSource.swift) with a CoreText fallback. - Verified API surface used by NEXTERM:
LocalProcessTerminalView(PTY viaLocalProcess+forkpty),LocalProcessTerminalViewDelegate(title, OSC 7 cwd, process exit),setProcessOutputHandler,findNext/findPrevious/searchMatchSummary,installColors,changeScrollback,allowMouseReporting,optionAsMetaKey,setCursorStyle, Kitty keyboard protocol, OSC 8 hyperlinks, accessibility service, fuzz corpus shared with Ghostty. - Proof of concept (
Sources/NEXTERM/App/NEXTERMApp.swift, Phase 0): a SwiftUI window hostingNEXTerminalView;-zshspawned as session leader on/dev/ttys012; keyboard input via System Events typedecho NEXTERM_OK cols=$COLUMNS lines=$LINES tty=$(tty)and the shell repliedNEXTERM_OK cols=112 lines=24 tty=/dev/ttys012(screenshots/tmp/nexterm-spike/spike{1,3}.png). - Build gotcha: SwiftTerm ships a build-tool plugin (
SwiftTermBuildInfoPlugin);xcodebuildrequires-skipPackagePluginValidation(Xcode IDE asks once to trust the plugin).
Decision
Use SwiftTerm 1.99.2 as the terminal engine, pinned exactly. Wrap it behind
TerminalCore.NEXTerminalView / TerminalSession so the engine is a replaceable implementation
detail. Revisit libghostty when its C API is declared stable; the spike script and log are kept
as the starting point.
Consequences
- No Zig or Metal Toolchain prerequisites;
xcodegen+ Xcode build everything. - Terminal fidelity is SwiftTerm's (xterm-256color, truecolor, alt screen, mouse, bracketed paste, Kitty keyboard/graphics); any gap found during acceptance testing is reported as such.
-skipPackagePluginValidationmust be passed toxcodebuild(handled byScripts/build.sh).