Swift 6.4 terminal core and frontends for macOS (AppKit) and iOS/iPadOS
(UIKit). SwifttyCore and SwifttyMobile also build for Mac Catalyst,
visionOS and tvOS. spec.md defines scope, protocols and acceptance requirements.
Shell embeds the core through its libghostty API.
Requires Xcode 27 and the tools pinned in mise.toml:
mise install
mise run build # debug build; `mise run release` for release
mise run test-native # full unit suite and real PTY sessions: sh, vim, less, tmux, top
mise run app # launch the macOS terminal
mise run test-internal # the same, with storage and terminal invariant checks
mise run bench # Release microbenchmarks; bench-storage for storage scaling
mise run lint
mise run format # format-check also validates documentation commentsPackaging and installation are under SwiftMux; the Ghostty comparison is under Measured results.
The native host runs tests serially because suites share AppKit state and use
blocking dispatch handoffs. Each manifest test bundle must exist and report a
complete run. A missing or failing bundle fails the command; later bundles still
run so their diagnostics are available. Completion is audited separately for
each bundle. Allocation budgets run only with optimized code;
Scripts/test-native.sh -c release checks them alongside the rest of the suite.
Use Xcode's Swift 6.4 toolchain, as CI does; mise.toml pins the other
tools but not Swift, because swift.org toolchains bundle a Swift Testing runtime
that conflicts with Xcode 27.2's and stops Scripts/test-native.sh from
finding tests. CI and release builds use the GitHub-hosted xcode-27 runner
(Apple Silicon, macOS 27, Xcode 27 / Swift 6.4 or newer) and enforce
Package.resolved; the shared setup action selects the newest installed Xcode,
verifies the toolchain and installs ripgrep and tmux for native tests.
Formatting follows the pinned Swift Collections configuration: two-space
indentation, 80-column wrapping and unindented conditional-compilation bodies;
generated Unicode tables retain their generator's layout.
Build the UIKit frontend with Xcode; the package's AppKit executable scheme is macOS-only:
xcodebuild -scheme SwifttyMobile -destination 'generic/platform=iOS Simulator' build
xcodebuild -scheme SwifttyMobile -configuration Release -destination 'generic/platform=macOS,variant=Mac Catalyst' CODE_SIGNING_ALLOWED=NO build
xcodebuild -scheme SwifttyMobile -configuration Release -destination 'generic/platform=visionOS' CODE_SIGNING_ALLOWED=NO build
xcodebuild -scheme SwifttyMobile -configuration Release -destination 'generic/platform=tvOS' CODE_SIGNING_ALLOWED=NO buildHosted mobile tests need XcodeGen and Python 3:
Scripts/test-ios-simulator.sh <simulator-udid>
Scripts/test-ipad-frame-time.sh <device-udid> <development-team>Both scripts retain results in a temporary workspace and print its path. Physical
tests use existing signing profiles. Simulator GPU timings are indicative only.
Recorded sh, vim, less, tmux and top sessions live in
Tests/SwifttyMobileTests/Fixtures; regenerate with
SWIFTTY_RECORD=1 swift test --filter SessionRecorder.
spec.shell.md defines the native swsh shell: batch
execution, scalar state and builtins, external and builtin pipelines, ordered
redirects, interactive editing/history, Darwin job control, literal exec,
functions, subshells, command substitution, native programmable completion,
app shell profiles, and bundled packaging. None of it aims at Bash
compatibility. The spec's
acceptance matrix and
implementation record hold test
coverage, recorded run scope, benchmark provenance, deliberate language limits
and remaining gaps.
swift build --product swsh
swift run swsh -c "name='two words'; /usr/bin/printf '<%s>\\n' \$name"
swift test --filter SwshTests
python3 Scripts/test-swsh.py "$(swift build --show-bin-path)/swsh"Scripts/test-swsh.py includes the failure-focused tests: nested child cleanup
and descriptor inventories, source-worker payload validation, function/subshell
interactions, and completion-provider contracts.
The batch CLI accepts -c source, one source-file path, or source on nonterminal
stdin. Source must be UTF-8 without NUL. Single quotes preserve all bytes between
them. Double quotes expand variables; a backslash escapes $, ", \, or a
newline there, and remains literal before other characters. Outside quotes a
backslash quotes the next character; backslash-newline continues a line. Unquoted
# starts a comment at a word boundary. $NAME, ${NAME}, and $? expand to one
scalar argument, including an empty argument for an unset variable. Expansion
never splits values or interprets their wildcard bytes. Only source-authored,
unquoted * and ? glob; unmatched patterns and ambiguous redirect targets are
errors. Matches sort by byte order.
Prefix NAME=value assignments see the pre-command state. Assignment-only
commands commit together; external-command prefixes form temporary environment
overlays. Builtin prefixes are errors. The fixed builtins are cd, pwd,
export, unset, exit, exec, return, complete, :, true, false,
jobs, fg, and bg.
cd uses a physical cwd and defaults to HOME; pwd accepts no options. export NAME exports the current
scalar (empty if unset); export NAME=value sets and exports it. unset removes
both value and export status. exit accepts one optional integer from 0–255,
defaulting to the last status. External commands resolve through PATH, or use
an explicit path containing /. There is no executable-format fallback.
exec program args replaces the current shell image through Darwin SETEXEC,
preserving its PID, cwd, process group, and inherited descriptors. In a pipeline
or background worker it replaces only that worker. This initial contract rejects
prefix assignments, redirections, and exec without a program. Main-shell exec
requires owned jobs to have finished first, so replacement cannot abandon their
supervisor. Failed lookup or replacement returns 127/126 and allows subsequent
commands; interactive failure restores the editor on the next prompt. Successful
replacement resets child signal dispositions/masks and closes private descriptors.
Lists support newline, ;, &&, and ||. Pipelines stream through kernel pipes
and return the last stage's status, including 126/127 lookup failures. Signals map
to 128 + signal. Redirects <, >, >>, <&, and >& apply left to right
after pipeline wiring; descriptor duplication accepts a number or - to close.
Parse/expansion errors return 2, redirect-open failures 1. Redirects also apply
to missing/inaccessible-command diagnostics; a redirect failure takes precedence
over the pending lookup status. Private launch payloads
are bounded to 8 MiB and validated against the exact executable hash. Shutdown
signals owned children, escalates external processes after two seconds, and fails after five seconds
if cleanup remains incomplete. Source workers retain their child-supervision lease
while reaping descendants; the parent avoids killing those reapers prematurely.
The lease closes on exec, so replacement programs remain subject to escalation. Batch mode keeps the inherited process group and
never signals that shared group during cleanup. Direct terminal sessions and mux
pane termination give the outer shell five seconds before forcing it to exit,
allowing shell-owned job cleanup to finish. Closing a mux frontend window still
detaches that frontend; explicitly ending a pane initiates shell shutdown.
For direct PTY hosts that create a session without assigning its controlling
terminal, interactive swsh claims the attached slave only when it is the session
leader and has no controlling terminal. Nested shells retain the foreground-wait
policy and cannot use this path to take another session’s terminal.
With terminal stdin, or explicit -i, swsh reads ~/.swshrc once and starts
its editor. Ctrl-C cancels the edit, Ctrl-D at an empty prompt exits, Ctrl-U clears
the line, Ctrl-W removes the last word, and up/down arrows browse history.
Editor input uses a separate nonblocking terminal handle so Ctrl-C flushing
cannot leave a stale readiness event blocked in read. Idle batch source input
also checks shutdown while waiting for bytes. Bracketed paste inserts source
without submitting embedded newlines. Tab completes
simple unquoted command/path words; quoted or expanded words are left unchanged.
History uses a separate mode-0600 ~/.swsh_history JSON-lines file, bounded to
1 MiB and 1,000 entries; individual submissions over 64 KiB are not persisted.
name() { commands; }defines or replaces a function, retaining its exact body source. Definitions are standalone, without redirects or&, and cannot replace fixed builtins. Lookup is explicit path, builtin, function, then PATH. A foreground standalone call runs in the current shell: assignments, exports, function definitions, completion registrations, andcdpersist. Prefix assignments to functions are rejected.$1through$9and$#are scalar parameters; nested calls restore the caller's parameters.return [0..255]ends only the current function, defaulting to the last status.exitretains its shell-exit meaning. Function recursion and parsed compound nesting are limited to 16 levels, including the top parser level.- Function redirections use supervised descriptor handoff and explicitly scoped I/O;
they do not replace the shell process's standard descriptors. State still persists.
Parent function redirects support destinations 0, 1, and 2; other destinations
require a subshell or pipeline worker so they have a real process FD namespace.
execinside a redirected function is rejected until descriptor replacement and failure restoration have a separate proof. Pipeline/background function calls run in source workers and cannot mutate parent state. ( commands )runs an isolated logical snapshot in a fresh source worker, preserving the inherited cwd and ordered redirects. It supports pipelines, background execution, nesting, and function lookup. The worker joins its outer job's process group; its children inherit that group. It has its own sole reaper and retires its children on exit. Terminal stop/continue signals therefore reach the compound job. No Swift code runs between fork and exec. Worker nesting is bounded at 128 processes.$( commands ), also inside double quotes, starts a separately supervised expansion job. Each selected command expands assignments, words, and redirects once before launch; short-circuited commands do not expand. Output is drained while the worker runs, preserves arbitrary non-NUL bytes, removes trailing LF bytes, and contributes one scalar without splitting or value-origin globbing. Empty output is an empty scalar. A nonzero worker status, stopped substitution, NUL, or output above 1 MiB is an expansion error (status 2); a stopped/oversized producer is aborted and reaped. Completed substitution effects cannot be rolled back if a later expansion fails.- Source workers receive exact body bytes and a value snapshot through the existing
bounded, unlinked, exact-build payload file. They bypass startup/history/editor
initialization and evaluate that body directly, without replaying already-expanded
caller words.
execreplaces the worker only and still refuses live owned jobs. complete command candidate ...registers literal candidates (zero candidates suppresses fallback).complete --function command providerregisters an existing function. The provider runs in an isolated worker with$1equal to the current unquoted token and$2equal to the input line. It prints one full candidate per LF-delimited line. Candidates are prefix-filtered, deduplicated, UTF-8 checked, and escaped before insertion; they are never parsed as executable source. Providers get/dev/nullstdin/stderr, no terminal handoff, a one-second execution deadline, a 1 MiB output limit, and bounded job cleanup. Failure offers no completion and preserves the shell's status/state. Timeout terminates only the provider job. Quoted/escaped/expanded input remains outside the initial editor completion contract.
greet() { /usr/bin/printf 'Hello, %s\n' $1; }
greet 'two words'
value=$(greet world)
(cd /; pwd) | /bin/cat
complete greet Alice Bob
names() { /usr/bin/printf 'Alice\nBob\n'; }
complete --function greet namesPipeline and background builtins run in fresh process workers. Their variable and
directory changes do not affect the parent, and worker exit ends only that stage.
They receive expanded arguments and only the logical values the builtin reads;
they do not load startup files, initialize history, or recursively launch workers.
Job-control builtins (jobs, fg, bg) require the main session and are rejected
as worker stages before any pipeline child starts. Standalone stateful builtins
run in the parent with explicit I/O descriptors. A supervised private helper
opens their redirects and transfers the resulting descriptors over a local socket;
it never executes the builtin. The parent commits state only after setup succeeds,
including for assignment-only commands with redirects. FIFO setup can be cancelled
with Ctrl-C or session shutdown. Setup shares the parent shell’s terminal-stop
policy; it is not a separately stoppable user job. exec still rejects redirects.
& schedules pipelines. jobs displays live jobs; fg and bg accept
an optional numeric job ID (with or without %) and default to the newest live job.
Ctrl-Z returns a prompt once every live pipeline stage stops. A stop ends that
submission: commands after it are not replayed by fg. Foreground resume restores
the job's saved terminal modes before SIGCONT; background resume leaves editor
modes alone. OSC 7 and OSC 133 are passive display metadata emitted only through
the controlling-terminal handle; SWSH_TERMINAL_METADATA=0 disables them.
Implementation and review checks cover Swift 6.4.1 and Apple Swift 6.4.2 with Xcode 27.2 and macOS SDK 27.2.
Isolated PTY fault probes cover later-stage spawn failure, shutdown immediately before group release, failed job-mode restoration before resume, and a simulated missed cleanup deadline. A missed deadline remains a failure on repeated shutdown calls. Batch stress checks cover completed-job retention, descriptor counts, and reaping across background jobs and pipelines with synthetic lookup failures.
A session actor owns a dedicated serial executor; one synchronous command driver
mutates language state. An awaited async defer shields only bounded shutdown
and terminal restoration. Cleanup yields between nonblocking reaping checks and
shares the launch-abort state machine and its original deadlines. Isolated tests
cancel before and during cleanup, cancel a caller while its foreground job runs,
reject a second evaluator during cleanup, and inject final terminal-restoration
failure. Cleanup finishes before the caller receives its status, and restoration
failure overrides a requested successful exit with status 1.
Run python3 Scripts/measure-swsh.py --output /tmp/swsh-measurements.json for
release measurements. It builds a separate instrumented executable for allocation
counts and per-process peak RSS, keeping timing measurements uninstrumented.
The 2 November language-growth baseline
records 360 timing samples and allocation/RSS observations before the subsequent
nested-cleanup and stop/resume hardening,
including function calls, subshells, and command substitutions. Its hashes identify
exactly what was measured.
The historical pre-review baseline contains raw samples, source/binary hashes, dependency revisions, and exact compiler/SDK/host metadata. On the recorded Apple M5 Max with 128 GiB RAM, 30 warm-cache timing samples gave:
| Workload | Median |
|---|---|
CLI startup and : exit |
4.38 ms |
| Private builtin worker startup, prewritten payload | 3.94 ms |
| Interactive first prompt, including PTY fixture setup | 9.41 ms |
| 16 MiB binary stream through three external pipeline stages | 147.6 MiB/s |
| 16 MiB stderr stream | 1,059.0 MiB/s |
After subtracting the median empty invocation, the measured amortized cost was 12.1 µs per parent builtin, 1.88 ms per builtin pipeline worker, and 3.30 ms per parent-redirect helper. The worker figure includes two-stage concurrency and is not an individual worker's startup latency. Instrumented runs observed a median 1,265 allocations across all threads and 6.66 MiB peak RSS for an empty invocation; builtin workers observed 1,320 allocations and 6.52 MiB each. The report retains initial-thread counts separately. Counts exclude allocations before the measurement constructor and after its destructor, and RSS is per process rather than the concurrent process-tree total. The measurements are local observations, not regression thresholds or proof of an ownership-feature speedup.
On macOS, TerminalSession.start(_:) can launch a PTY child. External
transports feed program output through receive(_:), send encoded input from
onWrite, and forward resize events to the remote program. Connection setup,
authentication and reconnection belong to the embedding app.
For a local macOS view, call TerminalView.start(_:) with an explicit
SessionConfiguration to preserve exact executable arguments, environment, and
cwd while retaining the view's grid and display lifecycle. Its parameterless
start() still uses the view configuration. onTerminalEvent forwards passive
events on the main actor after built-in handling, alongside onTitle and
onExit. Metadata can be coalesced or forged by terminal programs; it is not an
authoritative command-completion API.
TerminalUIView(session:configuration:fontSize:) hosts a session. An iOS app
target can use SwifttyMobileAppDelegate and SwifttyMobileSceneDelegate for
the reference demo. SwifttyMobile includes no app project or network
client; the roaming SSH clients under Apps/ provide both (see Roaming SSH).
visionOS omits accessory views, input clicks, haptics and screen-coordinate
keyboard avoidance. tvOS additionally omits the clipboard, edit menus,
pointer, hover, pinch, long-press and pan gestures: the focus engine can focus
the view, the select button makes it first responder, and hardware or system
keyboards provide input.
TerminalSession(presentationColumns:rows:configuration:) creates a session
that displays frames produced by another, authoritative terminal (for example
a roaming host). It never parses program output or encodes input:
installPresentation(_:) validates a PresentationFrame and replaces the whole
screen atomically, keeping the frame's cell widths, graphemes and wraps without
reflow, and marks it fully damaged. send forwards committed text, key presses
and pastes to semanticInputHandler (never onWrite), resize proposes the
view's grid to gridProposalHandler, and its own history is disabled:
scrollViewport(by:) goes to viewportScrollHandler, which a roaming client
turns into an RST/1 Viewport request so the host presents that client's own
history window (hosts advertising historyViewport). Local selection and copy
work on the displayed frame.
Both frontends expose a settable capabilities: SurfaceCapabilities (default
.full; set .roaming for remote presentation). Program-initiated clipboard writes (OSC
52) reach the pasteboard only with remoteClipboardWrites. Without the
matching capability, link opening, search, scrollback, mouse reporting, paste,
copy and text input are hidden or disabled rather than shown as nonfunctional
controls; presentation sessions also disable local resets and raw-byte
bindings. On UIKit, hidesContentWhenInactive covers the terminal while its
scene is inactive or in the background, so app-switcher snapshots omit it.
Shell input disables autocorrection, capitalization, spell checking, smart
quotes, dashes and insert/delete, and inline prediction.
OSC 7501 is opt-in through SessionConfiguration.programStatusEnabled or
setProgramStatusEnabled(_:). Read programStatusSnapshot, subscribe through
onProgramStatusChange, and route onTerminalReply to the originating transport.
External transports call programExited() when the program or connection ends.
The program-status contract specifies validation,
lifecycle and reply provenance.
spec.multiplexer.md describes a persistent session
service for Swiftty. A per-user LaunchAgent (swiftmux-agent) owns the shells,
PTYs, terminal engines, history and workspace layouts. Frontends connect to it
over one Mach/XPC endpoint using SMX/2: tagged JSON records that carry full,
validated pane frames.
swmuxis the terminal client. With no command it attaches to the newest workspace or creates one. Commands:new [-s NAME] [-c DIR] [-d] [-- CMD],attach [-t NAME],list(ls),detach,end -t NAME,end-all,statusandagent install|uninstall|status. Attaching runs only inside Swiftty (TERM_PROGRAM=swiftty, or pass--allow-host). The prefix isC-b; pressC-b ?for the bindings. Settings live in$XDG_CONFIG_HOME/swmux/settings.json(default~/.config/swmux):prefix,escapeDelayMillisecondsandremainOnExit.- The service links only
SwifttyEngine: the parser, terminal state, history, input encoding and PTY code, with no Metal, fonts or AppKit.SwifttyCorere-exports the engine and adds the renderer, fonts and sessions. - Every Swiftty app window is a SwiftMux workspace: a plain shell is a
workspace with one tab and one pane, and adding tabs or splits grows the
same workspace without restarting its shell. One-tab windows show a title
instead of the tab strip. Panes render service frames directly through
Metal. AppKit draws the tab strip (icons, titles, activity dots,
double-click to rename), pane headers and draggable, VoiceOver-adjustable
dividers. Shortcuts: ⌘N new workspace (in its own window), ⌘T new tab,
⇧⌘O open an existing workspace, ⌘W close the window (detaches),
⇧⌘] / ⇧⌘[ next/previous tab, ⌘D / ⇧⌘D split, ⌥⌘arrows focus,
⌃⌘arrows resize, ⇧⌘↩ zoom, ⌥⌘W end pane, ⌃⌘W end tab. The Workspace menu also
renames tabs and workspaces and ends a workspace; swiftty › Terminal
Service stages and installs app updates without replacing the bundle under
a live service. Only the End commands terminate processes, and ending a
running pane, tab or workspace asks first. Opening a workspace already
shown reveals its window; one controlled elsewhere is taken over only
after confirmation. At launch the last workspace reopens when free;
otherwise existing workspaces are offered before a new one is created.
New workspaces follow
commandandworking-directory(inheritmeans the app's own directory); new tabs reuse the workspace's command, and splits start a login shell in the split pane's directory. Find (⌘F, ⌘G, ⇧⌘G) searches the service-side history, key bindings and font zoom apply to panes, and app theme changes update the colours panes report to programs. Panes match the direct terminal: mouse reporting to programs (Shift still selects), the alternate-screen wheel,copy-on-select, ⌘-click and ⌘-hover links (link-url),cursor-click-to-move,mouse-hide-while-typing,custom-shader, prompt jumps, Select Command Output, Clear Screen and Reset Terminal. The service performs the ones that need the emulator; a service started by an older build lacks them, so their menu items are disabled until it is updated. Quitting the app detaches every window; the shells keep running. If the helper needs approval or is unavailable, the app says so and offers a retry; it never starts a non-persistent shell instead. - Panes start through
swmux-launcher, which callslogin_ttyand then execs the shell. They run withTERM=swmux-256color; the agent compiles that terminfo entry into~/Library/Application Support/SwiftMux/terminfo.
swift build
.build/debug/swmux agent install # development LaunchAgent for this build
.build/debug/swmux new -s work # inside Swiftty
mise run package-swiftmux [identity] # Swiftty.app with the bundled agent (SMAppService)
mise run install [--roaming] # package, install to /Applications, register the agent (+ swifttyd)
Scripts/install-ios.sh --team TEAM # iOS/iPadOS app on iPhones and iPads connected by USB
mise run uninstall [--purge] [-y] # remove the app, agent and swifttydinstall.sh signs with the first Developer ID Application identity (else
ad-hoc), and re-registers the agent when its signing team changes, or for an
ad-hoc build when its agent binary changes: launchd otherwise refuses to start
it (a launch-constraint violation). It then installs the iOS/iPadOS app
(MobileClient) on every paired iPhone and iPad connected by USB, signed
automatically for the Mac build's team or --team; --no-devices skips this.
Devices must be unlocked and in Developer Mode. The bundled
agent can also be managed directly with
Swiftty.app/Contents/MacOS/swiftty --swiftmux-agent register|unregister|status.
Installation uses Python 3 to copy the new app into a private sibling directory,
check its bundle/executables and verify its signature and expected signing team
before publication. An
atomic exchange replaces an existing app; a first install refuses a concurrently
created destination. Copy, validation or publication failures keep the previous
app in place. Filesystems that refuse the atomic operation stop installation.
Registration and optional roaming setup run after publication; they are separate
steps. Interrupted copy/verification workers are killed and collected, and
temporary-directory cleanup failures report the retained directory.
Before replacement, the installer checks the destination bundle's running
application through swiftty --running-app APP_PATH. A running copy there is
left alone; otherwise the installer opens the selected installation as a new
instance, even when another copy with the same name or bundle identifier is
running elsewhere.
uninstall.sh requires Python 3 to limit each shutdown command to ten seconds.
Failed or timed-out shutdown checks preserve installation files and state.
Repeated signals cannot replace an interruption result or abandon command
collection. Captured command output is limited to 64 KiB and is published only
after the command exits within its budget.
Acceptance evidence and measurements (mise run bench-swiftmux) are recorded
in section 11 of spec.multiplexer.md.
The service enforces the limits in MuxLimits: 32 panes, a 256 KiB input
buffer per pane, 16 MiB frames, 1 MiB pastes and a bounded history per pane.
Attention items (OSC 7501) can be opened from a link, as described in section 4
of spec.inbox.md:
swiftty://attention/open?ref=<locator>
https://<configured domain>/a/<locator>
-
MuxNavigationholds the typedAttentionDestination: the recipient's host profile ID, service epoch, workspace, tab, pane, terminal epoch, record path and incarnation, occurrence and intent (review,resultorreveal). It also has the locator codec, link validation andAttentionNavigator, a state machine for the navigation steps. It needs only Foundation and builds for every platform, watchOS included.MuxNavigationSMXadapts the navigator to a local SwiftMux connection. -
The locator is a versioned binary record of IDs, encoded as base64url. It holds no endpoints, hostnames, usernames, credentials, message text or commands. It is not an authentication credential. The app resolves a link only against hosts the recipient has configured. If the host is unknown, the app asks the user to pick one. It never connects to anything named in the link.
-
The app checks a link before it contacts anything. The scheme or configured domain must match, the link must be at most 2 KiB, the path must match, and the URL must have exactly one
refand no other parameters. The locator must decode strictly. The app then checks the service epoch and the exact occurrence before it shows any metadata. If the item is stale, superseded, missing or from before a service restart, the app says so and never shows a different request in its place. "Open in pane" attaches without taking over. If another client holds the workspace, the app asks for an explicit takeover tied to the lease generation the user saw. The app marks only the linked occurrence seen. -
On macOS, Swiftty handles the
swifttyscheme (CFBundleURLTypes, written byScripts/package-swiftmux.sh). It reveals the window that holds the linked workspace, or opens one (other workspaces' windows stay attached), and focuses the pane. Prompts appear as alerts. -
The roaming clients (iOS/iPadOS, Catalyst, visionOS, tvOS and the Mac client) register the scheme through
Apps/Config/AttentionLinks.plist. They routeonOpenURL, web-browsing activities and attention Handoff into a destination sheet. Attention travels over the SSH bootstrap channel (no-PTYswifttyd bootstraprequests, spec.inbox.md §3.6), not RST/1. The apps show one Inbox across every configured Mac; opening an item resumes the roaming attachment and asks before taking over a held workspace. There is no push delivery. -
Universal Links are off unless
SWIFTTY_LINK_DOMAINSis set. It is a comma-separated list of hostnames, validated byScripts/link-domains.sh(an invalid name fails the build). When it is unset, no target gets the associated-domains entitlement and onlyswiftty://links work.links.example.invalidis a placeholder only.# 1. The association file each domain serves, with no redirects, as # application/json at /.well-known/apple-app-site-association. # It claims only /a/<locator> (one component, no query or fragment). Scripts/make-aasa.sh -o apple-app-site-association TEAMID1234 \ com.chr33s.swiftty dev.chr33s.swiftty Scripts/make-aasa.sh --check apple-app-site-association # re-validate rule order # 2. Native macOS app: Info.plist SwifttyAssociatedDomains plus the # signed com.apple.developer.associated-domains entitlement. SWIFTTY_LINK_DOMAINS=links.example.com \ SWIFTTY_PROVISIONING_PROFILE=Swiftty.provisionprofile \ Scripts/package-swiftmux.sh "Developer ID Application: …" # 3. Roaming clients: XcodeGen's preGenCommand (Scripts/configure-links.sh) # writes Apps/Config/Generated/ with the domain list and per-target # entitlements for MobileClient, CatalystClient and # VisionClient. tvOS stays swiftty:// only. SWIFTTY_LINK_DOMAINS=links.example.com Scripts/build-platforms.sh
SWIFTTY_LINK_MODE=developersignsapplinks:<domain>?mode=developerso development builds fetch the association file directly instead of through Apple's CDN. Both generators preserve that literal suffix regardless of filenames in the working directory. Association-file validation requires the path, query and fragment exclusions before the inclusion rule and rejects matching defaults or conditions that change those rules. The macOS entitlement is honoured only with a provisioning profile that has the Associated Domains capability; withoutSWIFTTY_PROVISIONING_PROFILEthe script warns. -
The watch shows redacted
AttentionSummaryvalues: category, app name, counts and time. Message text is hidden by default. The watch can offer a Handoff (AttentionHandoffRequest) to a paired device, but it never takes a lease or sends input. Companion contexts and replies use wire version 3, so both paired apps must support it. Versions 1 and 2 are rejected. The phone persists publisher identity and publication sequence; status, attention and preview remain in memory. Publication order is separate from the original observation timestamps. Preview text is bound to an opaque selection id that changes when the selected session changes. That id is not a host or session token. The watch drops cached preview text when the id changes, when preview is disabled, or when a status reply says no preview can be served. A NaN or infinite refresh timeout uses the finite 15-second default.
Every SwiftMux pane parses OSC 7501 program status (protocol revision 0.3), whether or not it is shown, attached or leased. The service reduces each change in stream order, then sends coalesced updates (spec.inbox.md §3):
MuxAttentionis a pure reducer with three separate models: the current status of each record, Needs you occurrences (one per stretch ofblocked), and the latest unreviewed failure and result of each source. A source is identified by service epoch, pane, terminal epoch (new after RIS), record path and record incarnation, never by program name or text. A fastblocked → working → blockedsequence produces two occurrences.done → workingkeeps the result. Prompts, process exit andclearresolve requests; silence never does.- The SMX commands
subscribeInbox,inbox(100 rows per page, opaque cursor),locateAttention,markSeen,snoozeandmarkReviewedneed no lease. They never resize panes and must match the occurrence exactly. Opening an item marks it seen but does not resolve it. Only failures and results can be reviewed.locateAttentionreports whether another frontend holds the workspace lease. - Limits: 64 records per pane, 16 MiB of decoded status text (resolved history
is evicted first, then the oldest results), 256 resolved items kept for
stale links, and 16 subscribers. A subscriber can have at most 64
unacknowledged updates; if it falls further behind, it gets a single
resyncupdate instead. - The native window's toolbar shows the Needs-you count. Its popover lists requests, failures and results as sanitized plain text. Open in Pane reveals the pane, and opening a workspace controlled elsewhere asks before taking over. Snooze (15 minutes, 1 hour or tomorrow at 9:00) hides a waiting request from the count until then, and Unsnooze brings it back. Mark Reviewed dismisses failures and results. Load More reads past the first 100 rows. A failed command is reported in the popover, or in an alert once the popover has closed. Stale or missing items are dropped and the list is reread. OSC 7501 reports status only: Swiftty never answers a request for the program.
spec.roaming.md (with its Swiftty integration in Appendix A) defines SSH clients for Apple platforms whose shells survive network changes: the per-user SwiftMux agent on the Mac owns the PTY and the authoritative Swiftty terminal, and clients receive complete current screens over QUIC instead of a byte log. There is no speculative echo; typing latency is ordinary remote echo. Appendix B of the spec records the design sources.
| Target | Role |
|---|---|
SessionCore |
IDs, limits, input ledger (client queue, host admission), lifecycle, backoff, transfer manifests |
ScreenProtocol |
RST/1 messages, framing, RFC 1950 snapshots, validation, snapshot scheduler, bootstrap envelope and attention metadata, RSTConnection |
SSHClient |
SwiftNIO SSH: host trust, password/Ed25519, exec, shell, SFTP v3 subset, resumable verified transfers |
SSHIdentity |
SSH identities (spec.ssh-identity.md): UUID metadata, Keychain storage policies, read-only resolution, bounded OpenSSH Ed25519 import, including passphrase-protected keys; client-only |
AppleTransport |
Network framework QUIC (ALPN rst/1, TLS 1.3, no 0-RTT), SPKI and exact-certificate pinning, host identity |
TerminalHost |
RST/1 host over the SwiftMux service (owns no PTYs): RoamingHost QUIC listener and grants, in-process SMX client, screen exporter, session registry, bootstrap/attention service, control socket, roaming configuration |
RoamingKit |
Headless client core: RoamingClient, semantic input, presentation frames and the bootstrap/connector/sink seams; links the engine only |
RoamingConnect |
RoamingKit seams bound to SSH (SSHBootstrapper, SSHShellByteChannel) and pinned QUIC (QUICGrantConnector); no renderer or UI |
TerminalSurface |
GUI client glue: frontend backends (roaming, ordinary SSH, local PTY) over TerminalSession; re-exports RoamingKit and RoamingConnect |
TTYKit |
Outer-terminal I/O shared by swmux and swroam: raw mode, input decoding, display-width text, cell diff renderer |
RoamingTerminal |
TTY frontend for RoamingKit: frames through TTYKit, decoded input as semantic operations, reconnect banner |
swroam (SwRoamCLI) |
mosh-style roaming client for any terminal |
CompanionModel |
Bounded watch/iPhone status DTOs; no Swiftty, SSH or QUIC |
HostConnection |
Pairing-code descriptor and _swiftty._tcp discovery contract (spec.connection-setup.md); Foundation only |
RoamingStore (Apps/Store) |
Saved hosts, SSH identity lifecycle, CloudKit metadata sync and transfer manifests; no UI, terminal or renderer code |
RoamingApp (Apps/Shared) |
Shared app model and SwiftUI for the direct clients |
swifttyd (Apps/swifttyd) |
No-PTY SSH helper: bootstrap --stdio, status |
Host setup (spec.inbox.md §1): swiftmux-agent serves remote clients from
the same process as the native app when a roaming configuration exists at
~/Library/Application Support/SwiftMux/roaming/config.json (or
--roaming-config PATH, or $SWIFTMUX_ROAMING_CONFIG) with an explicit
bindAddress, advertisedHost and UDP port (51222 by default), plus an
optional stateDirectory. A relative state directory is resolved against the
directory of the selected configuration file, so the agent and SSH helper select
the same control socket independently of their working directories. A missing
default configuration disables roaming. A missing explicitly selected file, or
an unreadable or invalid configuration, exits with status 78 before the agent
starts its service. --no-roaming ignores the file; the last roaming option wins.
--idle-exit SECONDS|never sets the local idle exit, which roaming disables.
Scripts/install.sh --roaming [--host H] [--bind A] [--port N] writes this
file (default <LocalHostName>.local, 0.0.0.0, 51222) and installs the
helper. Enable Remote Login yourself. The signed bootstrap helper lives at
/usr/local/libexec/swifttyd; it only relays bootstrap --stdio to the
service's control socket (swifttyd status checks it). RST/1 session IDs
are SwiftMux workspace IDs, the grant's server instance is the service
epoch, and each attachment takes the workspace's interactive lease: a
workspace the Mac app controls is refused (writerBusy) unless the client
resumes with takeover. Grant expiry never ends a shell the remote client
did not create.
From any terminal, swroam [-i KEY] [user@]host bootstraps over SSH and then
follows the session over QUIC through network changes and sleep, like mosh,
but drawing the host's authoritative screen with no local prediction. It
accepts OpenSSH Ed25519 keys (default ~/.ssh/id_ed25519, passphrase
prompted) or a password, and asks once about an unknown host key before
raw mode; reconnects never prompt. Trusted keys live in
~/Library/Application Support/swroam/known_hosts.json. In the session,
Ctrl-^ . detaches (printing the swroam -r ID host to resume), Ctrl-^ k
terminates the shell, and Ctrl-^ Ctrl-^ sends Ctrl-^.
To allow incoming connections to the bundled swiftmux-agent through the
macOS firewall, run Scripts/install.sh --roaming --configure-firewall.
This uses sudo to add and unblock the installed agent, verifies its exception,
and reapplies it on repeat installs. The exception covers the executable,
rather than a single UDP port. Setup reports whether the firewall is disabled
or Block all incoming connections overrides the exception; global firewall
settings stay unchanged. Other firewalls, routers and managed network policies
may still need to allow the configured roaming UDP port. A configured exception
does not verify reachability from another device. Without --configure-firewall,
setup leaves firewall policy unchanged.
The roaming clients are one universal-purchase app, dev.chr33s.swiftty:
MobileClient (iOS/iPadOS, embedding WatchCompanion as
dev.chr33s.swiftty.watchkitapp), CatalystClient (macOS), VisionClient
and TVClient are platforms of one App Store Connect app, so testers see a
single TestFlight entry. Swiftty.app is the Mac terminal and host; Mac users
reach remote sessions through the Catalyst build.
Apps/ci_scripts/ci_post_clone.sh drives Xcode Cloud: it installs XcodeGen,
generates Apps/Swiftty.xcodeproj and copies Package.resolved into
it (Xcode Cloud never resolves packages itself). Create one Xcode Cloud
product for the app, pointed at Apps/Swiftty.xcodeproj, with
SWIFTTY_TEAM_ID (and optionally SWIFTTY_LINK_DOMAINS) in the workflow
environment, and one workflow with an archive action per platform, each
with a TestFlight post-action:
| Scheme | Archive platform |
|---|---|
MobileClient |
iOS |
CatalystClient |
macOS |
VisionClient |
visionOS |
TVClient |
tvOS |
tvOS and visionOS need layered icons (Apps/TVClient/Assets.xcassets with
the Top Shelf images, Apps/VisionClient/Assets.xcassets); regenerate them
from icon.svg with xcrun swift Scripts/gen-platform-icons.swift.
Swiftty.app is unsandboxed (it owns local PTYs) and is distributed with
Developer ID. .github/workflows/release-mac.yml runs on the GitHub-hosted
xcode-27 runner for a pushed v<version> tag (or manually, as a
mac-v<version>-<build> prerelease): Scripts/package-swiftmux.sh builds and
signs it, then Scripts/release-mac-github.sh notarizes it (Scripts/notarize.sh,
shared with the package and install scripts) and uploads a zip and SHA-256 to
the release, or to an existing draft for the tag. The workflow imports
the Developer ID certificate and private key into a temporary keychain from the
base64 MACOS_CERTIFICATE_P12 secret and its MACOS_CERTIFICATE_PASSWORD secret,
then removes the keychain after the release, including on failure. It also needs
the repository variable DEVELOPER_ID_IDENTITY and an App Store Connect API key as the secrets
NOTARY_KEY_ID, NOTARY_ISSUER_ID and NOTARY_KEY (the .p8 contents).
spec.connection-setup.md covers client setup. To set up a device:
- On the Mac, open Terminal Service › Connect a Device…. The panel shows
the SSH host, port and account; the configured roaming endpoint; local
checks of SSH and
swifttyd; and the SSH host-key fingerprints. Turn on Show Pairing Code for a QR code, or Make Discoverable While This Panel Is Open to advertise_swiftty._tcpon the local network. Closing the panel stops advertising. The panel never turns on Remote Login or changes the firewall or roaming configuration. - On the iPhone or iPad, open Settings › Connect to Mac and choose Nearby Macs, Scan Mac Code, Paste Mac Code or Enter Address Manually. The app asks for Local Network access when it browses or first reaches a LAN address, and asks for camera access only when you scan. A code's SSH key fingerprints must match before any password is sent, and an unknown key still needs an explicit Trust.
- After sign-in, choose a workspace, or choose New Workspace. Opening a saved host always shows this list; nothing is created automatically. Taking control of a workspace that another client holds needs your confirmation.
SSH and roaming use separate addresses. The device first reaches the Mac
over SSH, then reaches the roaming endpoint that the Mac's configuration
advertises over UDP. A <LocalHostName>.local endpoint works only on the
local network or a VPN that carries it. If SSH works but that endpoint does
not, the app shows "SSH connected; roaming endpoint unavailable" with the
address it tried.
Clients bootstrap with ssh <mac> /usr/local/libexec/swifttyd bootstrap --stdio
(a no-PTY exec with a length-prefixed JSON request), receive a session grant
with the agent's certificate, its SPKI pin (SHA-256 of the certificate's
SubjectPublicKeyInfo) and a bearer token, and attach over QUIC. The TLS
handshake must present that key and that exact certificate before the token is
sent; a changed pin fails closed (spec.inbox.md §1.8). The apps are generated
with XcodeGen:
Scripts/build-platforms.sh # iOS, macOS, Catalyst, visionOS, tvOS, watchOS, swifttyd
mise exec -- swift test --filter "ProtocolTests|IntegrationTests"IntegrationTests/EndToEnd runs the real registry, PTY, QUIC listener, pinned
client and a presentation-mode display, with and without an in-process SSH
server. Simulator runtimes:
Scripts/test-roaming-simulator.sh <ios-or-ipad-udid> [iOS|tvOS|visionOS] # client in the simulator vs a real roaming SwiftMux agent
Scripts/test-companion-watch.sh <watch-udid> # companion tests hosted by the watch app
Scripts/test-real-ssh.sh # real OpenSSH (apple/container Linux VM) + real swifttyd
Scripts/test-app-ui.sh '<xcodebuild destination>' [xcodebuild args] # XCUITest of a client app vs real OpenSSH + swifttyd
Scripts/test-keychain-signed.sh '<destination>' [team-id] # signed, app-hosted Keychain testtest-roaming-simulator.sh accepts --configuration release to build both
the native host products and simulator test bundle in Release; it defaults to
Debug. The fixture records the selected configuration alongside its results.
test-real-ssh.sh needs container. swifttyd is macOS-only, so the Linux
VM's /usr/local/libexec/swifttyd relays bootstrap --stdio to an agent on
this Mac. macOS Local Network privacy can deny test runners a route to the VM
subnet, so the script reaches sshd through container exec.
Set RST_REAL_SSH_CONFIGURATION=release to build and run the host, launcher,
bootstrap helper and test bundle in Release; the default is debug.
The wrapper compiles tests before starting the fixture and runs them without
rebuilding while the host is live.
The fixture keeps a private process owner for each host/bridge/relay, the UI-test
build (xcodebuild.log) and optional Bonjour advertiser (advertiser.log). stop
authenticates those owners and waits for child exit, escalating after six seconds
while allowing the proxies to reap their own children. PID files alone never
authorize signals. Missing owners, legacy PID-only records and failed cleanup
retain their markers and return an error. A start.lock prevents concurrent
startup/stop; if startup was forcibly killed, verify it has ended before removing
that lock and retrying cleanup.
The UI wrapper polls the collected build status so cancellation can stop an
active build before retiring the rest of the fixture. A build that ignores TERM
is killed and reaped after the same six-second grace period.
Container deletion and listing each have a ten-second deadline and capped output.
The container marker clears after successful deletion, or after a successful,
validated listing confirms the recorded VM is already absent; failed commands
and malformed listings alone never establish absence.
Roaming verification record (2026-10-10, Xcode 27.0, OS 27 SDKs):
| Destination | Evidence |
|---|---|
| iPhone 16, iOS 27.0.1 (physical) | App UI flow over LAN to real swifttyd + OpenSSH; signed Keychain; A2: 50 Wi-Fi↔5G switches over Tailscale, one retained shell, no duplicated input (Tests/DeviceHandover/Evidence) |
| iPad Pro 12.9" (5th gen), iPadOS 27.0.1 (physical) | App UI flow over LAN; signed Keychain |
| macOS 27 native, Mac Catalyst | App UI flow; signed Keychain (Apple Development) |
| iOS, iPadOS, tvOS, visionOS simulators | Roaming runtime test vs real swifttyd; Keychain |
| watchOS simulator | Companion tests hosted by the watch app |
| macOS host | Unit, integration, end-to-end QUIC and real OpenSSH suites |
QUIC connection migration: clients enable it (multipathServiceType = .handover), but Network framework's QUIC listener on the OS 27 SDK keeps
replying to a client's old address, so a path change ends in reattachment to
the retained session instead (spec §9 fallback). MigrationTests documents
the listener behaviour and RoamingEndToEndTests checks recovery to the same
shell with each command applied once.
Still open (spec §2.4, §13): physical Apple TV, Vision Pro and paired Apple Watch runs.
Scripts/test-handover.sh <iphone-udid> [switches] [team-id] runs A2: a standalone app
on the phone keeps one roaming session open while you toggle Wi-Fi, and the
retained shell on the Mac logs one line per switch.
spec.ssh-identity.md makes an SSH key a reusable
identity. Settings › SSH Keys (or New Key in the host editor)
generates an Ed25519 key or imports an OpenSSH Ed25519 private key from a
file or an explicit paste; a passphrase-protected key asks for its passphrase
once, which is not saved. Hosts select a key by UUID, so renaming never breaks them. Add the shown public key
to ~/.ssh/authorized_keys on the Mac yourself. Signing in only reads the
selected key: a missing, locked, deleted or mismatched key fails closed, never
generates a replacement and never falls back to a password.
Keys are device-only by default (WhenUnlockedThisDeviceOnly, never
synchronized). A key created or imported as iCloud Keychain is
synchronizable (WhenUnlocked); the policy is fixed per key, with explicit
Create iCloud Copy and Withdraw from iCloud actions that make a new key.
Items use service dev.chr33s.swiftty.ssh-identity.v1 and the access group
$(AppIdentifierPrefix)dev.chr33s.swiftty.
Settings › iCloud Sync separately opts in to syncing host profiles and
public key metadata, and trusted host keys, through the private CloudKit
database (zone SwifttyConnectionsV1). Both are off by default and only appear
when the clients are generated with SWIFTTY_CLOUDKIT_CONTAINER set to a
provisioned container (Scripts/configure-links.sh). Sync runs in the
foreground only, never carries private keys or passwords, and keeps another
iCloud account's data hidden after an account switch. tvOS keeps local key
sign-in and generation, without import or sync.
iCloud key operations use the configured account provider even when metadata sync is off. Interrupted operations retain their original account; enabling metadata sync does not move another account's pending work. Older interrupted creations without account information require explicit Restore in SSH Keys. Older removals appear under Key Removals Needing Review. Review the fingerprint before authorizing removal from the current iCloud account; failed removals remain queued for retry. Returning to the foreground retries interrupted key operations even when metadata sync is off. Completed iCloud keys also stay with their original account. Older descriptions without account information appear under Keys Needing Account Review; restoring one verifies its fingerprint in the current account without enabling metadata sync. Builds without an account provider still support device-only keys.
hosts.json uses a version-4 snapshot of all non-secret connection state.
It preserves separate account caches when record names collide and upgrades
version-2 and version-3 snapshots, retaining records and queued edits while
requiring review for older iCloud keys with unknown account ownership.
Version-1 key labels migrate to device-only identities with the same key and
fingerprint. Migration keeps the original file as hosts.v1.json and removes
each legacy Keychain item only after its replacement is verified. Earlier builds reject the version-4 file when
loading it.
The session, snapshot, input, configuration, and frontend APIs are the embedding
surface. This pre-1.0 package provides source compatibility within patch releases;
minor releases may change public APIs. Internal and package declarations have
no compatibility guarantee. Physical row ids, pointer access, storage pools, and
benchmark hooks are implementation details.
Grid.cells(row:), Grid.historyCells(at:), TerminalState.viewportCells(row:),
and TerminalState.scrollbackCells(at:) return borrowed spans. End each borrow
before mutating its owner. Grid writes require exclusive access;
withMutableCells(row:_:) updates the row extent even when its closure throws.
Indices and allocation sizes are checked before accessing memory. Nonpositive
screen dimensions are clamped to one.
History storage is reclaimable and, on macOS and iOS/iPadOS, compressed when
idle. History
chunks use dedicated page-aligned mappings divided into compression units of at
most 256 KiB; after 250 ms without output, input, viewport or resize activity,
the owning session or SwiftMux pane encodes at most one unit per step on its own
queue (LZ4 through Apple's Compression framework, verified by CRC-32C). The
viewport, recent captures, the next eviction rows and both live screens stay
resident. Warm row access is O(1) with no Swiftty heap allocation; a cold
borrowed read restores its units in place, costing O(bytes of those units)
plus page commitment, and never invalidates another borrowed row. Search,
selection copy, ANSI dumps, link detection, OSC 8 reclamation, invariant checks
and reflow read cold history through at most two units of scratch without
restoring it. Clearing history drops compressed units without decoding them and
returns fully free units' pages to the system. Retention limits count
uncompressed history cells, so compression never changes which rows are kept.
Compression runs no timers when idle and never redraws, publishes, or changes
addressing or search generations. A compressed unit that fails its integrity
check traps (fail-fast). macOS and iOS/iPadOS use this backend; Catalyst,
visionOS and tvOS keep uncompressed heap chunks.
TerminalState.scrollbackStatistics reports logical, resident, compressed,
metadata, workspace, protected, eligible and reclaimed bytes from metadata
alone; scrollbackCompression reports the requested and effective policy with
the fallback reason.
Snapshot spans borrow the snapshot. Retaining a snapshot preserves its cells
while later frames reuse other pool entries. Grapheme ids belong to the snapshot
that produced the cell; passing a cell from another snapshot to
graphemeScalars(_:) is invalid even when the numeric id happens to match.
SWIFTTY_INTERNAL_CHECKS (mise run test-internal) validates row ownership,
ring bounds, blank extents, grapheme references, and wide-cell structure at
completed parser batches and storage bounds after mutations. Checks and their
scratch storage are absent from normal builds. Storage benchmarks vary size and
ring layout, exclude setup from timing, and report consumed results alongside
nanoseconds per operation; run them in Release without internal checks.
At launch, Swiftty provisions ~/.config/swiftty/config.js, jsconfig.json
and swiftty.d.ts. The declaration file updates with the app; existing scripts
and editor configuration are preserved. Open this directory in a JavaScript /
TypeScript-aware editor for completion and inline type checks. Node.js and npm
are not required by the application.
The persistent SwiftMux service evaluates the script once before its first pane starts. Script edits take effect in the next service process; closing and reopening a window does not restart that service or reload JavaScript. The ordinary configuration reload command below applies to the active terminal configuration file; JavaScript reloads separately.
The global swiftty provides stdin/stdout filters, environment lookup, managed
pane writes/splits/closes, shortcuts, dock badges, tab labels, native notifications
and left/right status items. Status renderers run once when registered, on manual
refresh, and optionally at a polling interval. Native notifications use macOS
notification permission and require the packaged application.
Lifecycle hooks have separate protocol sources:
events.onCommandFinished: OSC 133 completion, with the command text when available and-1for an unavailable exit status.events.onDirectoryChanged: OSC 7 directory changes.events.onStatusChanged: validated OSC 7501 reports, removals, resets and authoritative resync snapshots from the same journal as the attention inbox. Each event identifies its pane and terminal epoch.currentPanerefers to the source pane during these callbacks.
swiftty.events.onStatusChanged(change => {
if (change.type === "report" && change.record.state === "blocked") {
swiftty.ui.setTabIcon("⏳");
swiftty.ui.notify(change.record.title || "Program needs attention",
change.record.message || "Waiting for input");
}
});Filters operate on individual UTF-8 chunks, so a match spanning chunks requires
state in the script. Invalid/incomplete UTF-8, throwing filters and results over
host byte limits pass through unchanged. Streamed pastes filter their payload
while preserving the writer's paste framing and sanitization. Script errors are
logged; one failing event listener does not prevent the others from running.
Automation scripts can read JSONC data using the same parser as terminal
configuration: swiftty.jsonc.read("automation.jsonc") loads a file beside
config.js, and swiftty.jsonc.parse(text) parses a string. Comments and trailing
commas are supported, with source-position diagnostics. Reads are synchronous
and limited to 1 MiB; load settings at startup. Data uses JavaScript number
precision and is never executed. Callback functions remain in config.js.
See the JavaScript specification for the API and OSC 7501 change semantics.
Swiftty supports JSONC configuration with // and /* … */ comments and
trailing commas. File discovery checks, in order:
swiftty --config <path>(a missing explicit file is reported).$XDG_CONFIG_HOME/swiftty/config.jsonc, or~/.config/swiftty/config.jsonc.~/.swiftty.jsonc, then~/.config/swiftty/config.json.
Configuration files are complete JSONC documents: Ghostty-style files, includes,
repeated keys and key = value lines are not supported, and the Ghostty themes
directory is not searched. Existing extensionless or legacy files are ignored by
discovery and left on disk; convert their settings to the JSONC model. With no
JSONC file, defaults apply.
Settings (Cmd-,) edits the selected file, including an explicit --config
path, and lists configuration problems; it will not overwrite an invalid file.
Edit Configuration File (Opt-Cmd-,) opens it, creating a commented template on
demand; Shift-Cmd-, reloads it. iOS reads Documents/config.jsonc. Reduce
Motion, Reduce Transparency and Increase Contrast adjust presentation without
changing the file (spec.apple.md).
Each omitted section or setting uses its default. Optional window.width and
window.height set the initial content size in points. scrollback_limit counts
history rows; the terminal's existing byte budget also bounds storage. A shell
is an executable path, not a shell command. The optional theme,
copy_on_select, mouse_hide_while_typing, cursor_style, and
cursor_style_blink fields support Settings edits. Unknown keys, invalid types,
and invalid ranges are reported with the original file, line, and one-based
UTF-8 byte column (tabs count as one). Duplicate keys are rejected.
Select a shell for new sessions in Settings › Shell or set
terminal.preferred_shell to system, bash, zsh, swsh, or custom.
Omitting it preserves the existing command and terminal.shell behavior.
Profiles retain their settings when you change the selection:
"terminal": {
"preferred_shell": "swsh",
"shell_profiles": {
"bash": { "arguments": ["--login"] },
"zsh": { "arguments": ["-l"] },
"swsh": { "environment": { "EDITOR": "vim" } },
"custom": {
"executable": "/opt/homebrew/bin/fish",
"arguments": ["--login"],
"working_directory": "/tmp"
}
}
}Arguments are passed literally. Set login or interactive flags explicitly;
the system profile retains the default login-shell policy. Profile environment
values override the frontend snapshot; SwiftMux still supplies terminal identity
variables. A selected profile applies to future workspaces, tabs, and splits;
running sessions keep their launch settings. The app bundle includes and signs
swsh alongside its other executables.
The dependency-free SwifttyConfig library provides ConfigDiscovery,
ConfigLoader, JSONCSanitizer, and mutable Codable models. ConfigLoader.save
validates and atomically writes pretty-printed, sorted JSON. Saving JSONC from
Settings or the library replaces comments with canonical JSON; symlinked
configuration files keep their links. schema.json provides editor completion;
the $schema URL resolves from the repository's main branch once published.
Themes use JSONC too. Place a file such as Night.jsonc in
~/.config/swiftty/themes and set "theme": "Night.jsonc". Built-in themes are
Swiftty Dark and Swiftty Light; omitting theme follows the system appearance.
On macOS these use native system text, background, selection and ANSI colors,
including the system selection accent. Other platforms use an Apple-colored
light/dark palette. The terminal defaults to 95% opacity over native glass;
Reduce Transparency makes it fully opaque.
A theme can also be selected by an explicit path.
{
"background": "#0C1021",
"foreground": "#F8F8F8",
"cursor": "#FFFFFF",
"cursor_text": "#0C1021",
"selection_background": "#253B76",
"palette": { "1": "#BF392A", "2": "#61CE3C", },
}Theme files must be regular UTF-8 files of at most 64 KiB; configuration files are limited to 1 MiB. Invalid themes fall through to the next lookup directory or built-in theme. Explicit unavailable themes use the standard palette.
Programmatic embedders can still set renderer/session properties directly, including font features, palette overrides, shader paths and command arguments.
Keybinding actions include clipboard operations, font sizing, selection, scrolling,
prompt jumps, search, clear/reset, text:…, csi:…, esc:…, ignore and unbind;
their names and parameters are defined in
Keybindings.swift.
Custom shaders use Metal and define
float4 postprocess(float2 position, texture2d<float> source, constant PostUniforms &u).
See PostProcess.swift for uniforms.
position uses pixel coordinates; normalize it for a coord::normalized sampler.
Shaders accessing u.time animate continuously. Memory aliases and preprocessor
directives enable animation conservatively; other shaders draw on demand.
Relative shader paths resolve against the declaring configuration file.
mise run unicode [EastAsianWidth.txt]
mise run graphemes <ucd-dir>The width generator needs matching PropList.txt,
extracted/DerivedGeneralCategory.txt and emoji/emoji-data.txt; without a path,
it downloads companion files from the same release. Grapheme data must match the
Ghostty comparison build. Both commands stage replacements and reject truncated
inputs missing their final # EOF or #EOF marker.
These are Release measurements on Apple Silicon; lower times are better. Physical iPad frame time and the centered onscreen comparison date from 2026-10-10; earlier probes are identified below.
Parser and terminal-state throughput on an Apple M5 Max (18 CPU cores, 128 GiB),
measured 2026-11-05: Ghostty 5dc28bb, Zig 0.16.0 ReleaseFast, versus Swift
6.4.2 Release. Each binary read the same ~100 MiB files in 64 KiB chunks at
120×80. Times are median CPU time (user + sys) of each process, including
startup and file reads; relative throughput by wall time, recorded alongside,
is within 1% of these except on kitty-long-escape-codes (4.6%) and
ghostty-ascii (1.1%). Each input had two warmups and 20 rounds in a balanced
(Williams) order, so every variant ran in each position and after each other
variant equally often. Intervals are paired bootstrap 95% intervals.
The 1-minute load average stayed between 1.7 and 3.4.
The inputs are ten Swiftty generators, four ghostty-gen generators and five
of kitty's kitten __benchmark__ payloads, built from kitty's source at
fb99338 and repeated as the kitten sends them, on the alternate screen.
kitty's Images payload is omitted: Swiftty ignores APC strings, so it would
skip all of Ghostty's image work.
Ghostty's terminal-stream raises its 10,000-byte scrollback limit to two
215-row pages, up to 350 history rows at 120×80; Swiftty applies 10,000 bytes
literally (5 rows). "Matched" gives Swiftty 350 rows (672,000 bytes) and is the
like-for-like comparison. kitty's payloads use the alternate screen, so history
does not apply to them.
With matched history Swiftty was faster on all 19 inputs, from 3.0% on
cat-source to 3.5× on ghostty-osc. The nominal limit gives the same
count. On 4 November, before the UTF-8 decoder and cluster changes, mixed
utf8 and kitty-unique-unicode were about 1.2% slower and utf8-latin
tied (samples).
Relative throughput is Ghostty time / Swiftty time.
| Input | Ghostty | Swiftty | Relative (95% CI) | Matched | Relative (95% CI) |
|---|---|---|---|---|---|
| ascii | 99.9 ms | 88.7 ms | 112.6% (112.3–113.2%) | 90.8 ms | 110.0% (109.7–110.5%) |
| cat-source | 149.5 ms | 139.7 ms | 107.0% (106.7–107.3%) | 145.1 ms | 103.0% (102.5–103.5%) |
| compiler-log | 142.7 ms | 110.4 ms | 129.2% (128.6–131.2%) | 111.6 ms | 127.8% (127.2–129.7%) |
| csi-heavy | 483.0 ms | 226.6 ms | 213.1% (211.6–214.6%) | 226.6 ms | 213.2% (212.0–214.4%) |
| osc-heavy | 1241.2 ms | 367.7 ms | 337.6% (329.8–343.0%) | 378.4 ms | 328.0% (320.2–335.2%) |
| scroll | 414.8 ms | 305.8 ms | 135.6% (134.2–136.4%) | 306.9 ms | 135.2% (133.2–136.5%) |
| unicode-joins | 667.7 ms | 347.6 ms | 192.1% (189.1–196.0%) | 361.6 ms | 184.7% (181.8–188.3%) |
| utf8 (mixed scripts) | 340.4 ms | 223.2 ms | 152.5% (151.8–153.0%) | 224.2 ms | 151.8% (151.1–152.3%) |
| utf8-latin | 132.5 ms | 123.3 ms | 107.5% (107.1–108.2%) | 124.6 ms | 106.4% (105.9–107.0%) |
| utf8-cjk | 101.7 ms | 93.5 ms | 108.8% (108.1–109.5%) | 94.3 ms | 107.8% (107.5–108.4%) |
| ghostty-ascii | 69.3 ms | 61.6 ms | 112.5% (111.4–113.1%) | 62.1 ms | 111.6% (110.3–112.5%) |
| ghostty-osc | 4389.5 ms | 1238.2 ms | 354.5% (349.7–355.7%) | 1249.6 ms | 351.3% (346.4–353.4%) |
| ghostty-styled | 421.7 ms | 184.4 ms | 228.7% (228.1–229.3%) | 185.2 ms | 227.7% (227.0–228.4%) |
| ghostty-utf8 | 766.4 ms | 385.8 ms | 198.7% (198.0–199.3%) | 388.4 ms | 197.3% (196.6–197.8%) |
| kitty-ascii | 167.7 ms | 156.2 ms | 107.4% (106.7–108.0%) | 156.1 ms | 107.4% (106.9–107.9%) |
| kitty-unicode | 97.4 ms | 85.2 ms | 114.4% (114.0–114.9%) | 85.0 ms | 114.6% (114.2–115.2%) |
| kitty-unique-unicode | 586.4 ms | 283.3 ms | 207.0% (206.0–208.4%) | 283.3 ms | 207.0% (205.9–208.4%) |
| kitty-csi | 426.0 ms | 273.7 ms | 155.7% (155.4–156.7%) | 273.1 ms | 156.0% (155.5–156.7%) |
| kitty-long-escape-codes | 13.9 ms | 12.3 ms | 113.3% (111.4–114.6%) | 12.3 ms | 112.6% (110.5–114.4%) |
Caveats:
- Upstream
ghostty-benchlogs warnings to stderr while timed. A build withlog_level = .errwas 23.1% faster onghostty-utf8, 15.6% onosc-heavy, 8.5% onkitty-long-escape-codesand 0.7–4.9% on the rest. Against it, nominal-limit Swiftty is at 161.4% onghostty-utf8and 291.9% onosc-heavy, and stays ahead on every input, by at least 3.1% (cat-source). With matched history it is ahead on all butcat-source(99.2%). - Final states are not compared. OSC 8 links follow Ghostty's rules: an
id=parameter and the URI identify a link, every other OSC 8 opens a link of its own, and URIs are kept whole. Swiftty keeps them in one table for both screens, stores each distinct URI once, and labels at most 1,048,575 live links. Adopting these rules leftghostty-oscwhere it was (351.4% before) and madeosc-heavyfaster (252.5% before). ghostty-gen +asciiand+oscare unseeded andcat-sourceconcatenates this repository's sources; compare input hashes across runs.- Median peak RSS: Swiftty 7.7–10.4 MiB, Ghostty 9.5–11.2 MiB.
Raw samples, input and binary hashes, load averages and toolchain versions are in Benchmarks/Ghostty/compare-2026-11-05.json. To reproduce:
# In the Ghostty checkout:
zig build -Demit-bench -Doptimize=ReleaseFast -Demit-macos-app=false
# In this repository (also builds swiftty-bench in Release):
mise run compare <ghostty-src> <corpus-dir> --generate--generate writes the inputs (ghostty-gen runs +ascii, +osc,
+styled --seed=42 --style-rate=0.3 and +utf8 --seed=42) and downloads
kitty's benchmark source at the pinned commit (--no-kitty skips it).
--metric wall switches the headline metric; --ghostty-quiet <src> adds the
log-suppressed build.
Against milestone 1 (67c8dfa), the current Release build passed all 18
text-only RSS cases: nine inputs at 120×80 with 10,000-byte and 10 MiB
histories, two warmup pairs and six alternating measured pairs. Median RSS
changes ranged from −30.7% to +0.74%.
Offscreen scrolling at 120×40, 20 lines/frame, improved p95 from 0.640 to
0.508 ms across 20 measured pairs after four warmups (paired change −0.129 ms,
95% interval −0.171 to −0.119 ms). Both builds used Swift 6.4; the display was
locked during this offscreen comparison.
Borrowed grapheme-cache lookups reduced warmed full-redraw allocations to 11 per frame, matching plain text. Median offscreen frame time fell by 17.7% for combining marks, 12.8% for ZWJ emoji and 10.0% for long clusters. Parser/grid allocation tests require zero steady-state allocations for common ASCII, UTF-8, CSI and cell updates. OSC metadata and table growth can allocate.
A physical iPad Pro (12.9-inch, 5th generation), iPadOS 27.0.1, measured the current core's 120×40 offscreen full redraw at p50 1.580 ms and p95 2.930 ms (20 warmups, 220 frames). Dense search highlights measured p95 3.030 ms (five warmups, 35 frames). GPU completion was awaited; both tests passed.
The current Swiftty AppKit view in a Release probe was compared with Ghostty 1.3.1 (15212) on the same M5 Max display. Both used Menlo 13, an 80×24 PTY, blinking disabled and the same raw-PTY response script.
Three serial alternating pairs posted synthetic keys to trigger alternating black/white backgrounds. The same independent ScreenCaptureKit observer detected these changes through a 32×32 crop at the display center, requesting 120 capture frames/s. Each run used 20 warmups and 100 measured responses; all 720 were observed. Ranges span runs.
| Terminal | p50 | p95 |
|---|---|---|
| Swiftty | 16.683–16.983 ms | 23.461–24.919 ms |
| Ghostty 1.3.1 | 18.574–21.319 ms | 24.665–25.661 ms |
Median paired p95 difference was −0.742 ms (Swiftty minus Ghostty). This measures synthetic key-to-captured-pixel delivery, including capture overhead; physical-keyboard, glyph-typing and photon-level latency have not been measured.
AppKit now uses two drawables. Matched foreground scrolling probes without Instruments used 900 updates at 60 Hz and 1,800 at 120 Hz per queue. Compared with the default three drawables, 120 Hz draw-to-presentation p95 fell from 40.7 to 32.3 ms; presentation-interval p95 stayed at 8.33 ms, with two-refresh intervals falling from eight to two. Neither run had presentation gaps over 100 ms; earlier multi-second profiled stalls did not recur.
Earlier physical iPad probes at 169×57 presented all 220 measured updates from a confirmed 120 Hz source after 20 warmups: presentation-interval p95 8.338 ms, synthetic output-to-presentation p95 24.748–24.797 ms. A 60 Hz probe measured latency p95 25.961 ms and presentation-interval p95 25.014 ms. All timestamps were positive. With blinking disabled, the probes observed zero draws during eight idle seconds and two background seconds with incoming output.
These results describe earlier tested builds. Current validation gaps are tracked in todo.md; historical device results do not verify the current tree.
The earlier macOS Debug/Release baseline passed 1,156 tests. Added keypad-mode coverage and 86 AppKit checks passed in both configurations. The hosted simulator passed 171 mobile tests. The physical iPad build tested then passed 169 correctness tests and two separate frame-time tests. Release builds passed for visionOS and Mac Catalyst.
Coverage includes Unicode batching, recorded sessions, shader classification, visibility/opacity recovery, animation suspension, momentum cancellation and accessibility. Native probes verified drawable recovery and draw suspension/restoration on both platforms. UI automation passed shell typing and Find navigation, highlighting, query/terminal focus and accessory-bar restoration, including narrow windows and resizing.
Physical keyboard, Find, VoiceOver, link navigation and browser-return redraw
checks passed on both devices; macOS also passed interactive vim/less, resizing
and scrolling. User checks passed blur and corrected static/animated shaders on
both devices. Scripted and hands-on USB shell checks with vim, less, tmux
and top passed on the physical iPad. The user reported typing and scrolling
equally responsive alongside Ghostty in the two-drawable Mac build.
Battery consumption has not been measured.
The consolidated backlog lists deferred
checks that need protocols or APIs Swiftty does not implement yet.
{ "$schema": "https://raw.githubusercontent.com/chr33s/swiftty/main/schema.json", "font": { "family": "Menlo", "size": 14, "line_height": 1.2, }, "window": { "opacity": 0.95, "blur": true, "padding": 8, }, "terminal": { "shell": null, "scrollback_limit": 10000, }, "keybindings": [ { "trigger": "cmd+k", "action": "clear_screen" }, { "trigger": "cmd+t", "action": "new_tab" }, ], }