Build from Source

Requirements#

• macOS 15.6 or later
• Xcode 16 or later, with Swift 5 and the macOS SDK

Clone#

git clone --recurse-submodules https://github.com/0x96f/justty.git justty
cd justty
open justty.xcodeproj

Already cloned without submodules? Fix it in place:

git submodule update --init --recursive

Build#

Select the justty scheme and run.

The app sandbox is off (ENABLE_APP_SANDBOX = NO) so Ghostty's .exec backend can spawn a real login shell. Turning the sandbox on breaks shells; see Architecture.

Tests#

Host unit tests use Swift Testing and live in justtyTests/:

xcodebuild -project justty.xcodeproj -scheme justty -destination 'platform=macOS' test

Updating libghostty#

Bump the Vendor/libghostty-spm submodule intentionally, pinning a known tag or commit. Clean DerivedData and rebuild afterward so you are not linking a stale binary framework.

If the build fails#

Troubleshooting covers unresolved packages, missing submodules, and stale frameworks.