Architecture
The SwiftUI host owns the app shell: windows, tabs, the tab bar, menus, and settings. It builds the terminal configuration and hands it down.
libghostty owns everything inside a terminal surface: VT parsing, the Metal renderer, scrollback, search, and the PTY.
Drawing that line where it is has consequences you can feel while using the app, so they are worth knowing.
The contracts#
Sandbox off, .exec backend
The app sandbox is disabled (ENABLE_APP_SANDBOX = NO). JusTTY uses Ghostty's .exec backend to spawn a real login shell, and the sandbox blocks that. This is why the app cannot ship through the Mac App Store, and why sandboxed or in-memory backends are out of scope.
If you build from source and enable the sandbox, shells stop working. See Troubleshooting.
The host owns configuration
JusTTY builds a TerminalConfiguration in Swift and passes it to the controller. It does not load a separate ghostty.conf. Your Ghostty config, if you have one, is not read.
Settings live in ~/.config/justty/config.yml instead. See config.yml.
keybind=clear, then the catalog
The host clears Ghostty's default keybindings, then installs its own from ShortcutsCatalog.swift. Without that clear, Ghostty's ⌘T and ⌘W would fight the SwiftUI menus for the same keys.
The practical result is the two-table split in Keyboard Shortcuts.
Tab parking
Inactive tabs stay mounted off-screen in a TerminalParkingView rather than being torn down. libghostty needs to keep draining exec events for a session that is still running, so a background tab running npm run dev keeps producing output and keeps its scrollback.
This is why switching tabs is instant and why a long build in tab 3 does not stall when you are working in tab 1.
Source layout#
| Layer | Path | Owns |
|---|---|---|
| App | justty/App/ |
Entry point, window group, menu commands, constants |
| Terminal | justty/Terminal/ |
Sessions, Ghostty config and host views, parking |
| Tabs | justty/Tabs/ |
TabManager, tab bar, content layout |
| Settings | justty/Settings/ |
AppSettings, themes, fonts, shortcuts UI and catalog |
| Window | justty/Window/ |
Chrome, geometry, drag region |
Related#
- Windows and Tabs — the behavior the Tabs layer produces
- Build from Source — the submodule that brings libghostty in