Build from source

Choose the correct build target#

For the Mac app, use an Apple silicon Mac with Xcode 26.6 or later; the project’s release and CI toolchain is Xcode 26.6. The downloadable app supports macOS 15 or later.

For headless daemon and CLI builds, the repository supports Swift 6.0 on macOS or Linux. The graphical app, Metal renderer, and Sparkle integration are excluded on Linux.

Build the Mac release app#

git clone https://github.com/robzilla1738/harness-terminal.git harness
cd harness
make release
open Harness.app

A local build is not the same as the signed and notarized published DMG. Public release distribution uses the separate signing and release process described in the repository.

Build headless components#

swift build -c release
./.build/release/harness-cli socket-path

Run the build from the repository root. See the remote-session guide for starting and connecting a daemon on another host. Do not assume compiling it also creates a persistent operating-system service.

Validate a source change#

swift build
swift test
HARNESS_LIVE_DAEMON_TESTS=1 swift test
make bench

The ordinary suite is the fast deterministic path. Live daemon tests exercise real sockets and PTYs and are important for daemon, IPC, and terminal-process changes. Benchmarks produce machine-readable timing lines; they are not a universal performance promise or a portable pass/fail threshold.

Work in Xcode#

The Xcode project is generated from project.yml with XcodeGen:

xcodegen generate
open Harness.xcodeproj
xcodebuild -project Harness.xcodeproj -scheme Harness \
  -configuration Debug -destination 'platform=macOS,arch=arm64' build test

The app target bundles HarnessDaemon and harness-cli so development uses the same helper layout as the release app. Review the release reference before changing signing, notarization, update feeds, or distribution automation.

Use a consistent 2.0 snapshot#

This documentation is pinned to product commit 340949a08f4673fe78183fded108f5c94c76ba61, the shipping v2.0.1 source. Check out that commit or the v2.0.1 tag and follow its build instructions and toolchain requirements.

Keep the Mac app, daemon, and CLI compatible when testing new workspace methods. For isolated preview builds, use both HARNESS_PREVIEW_HOME and HARNESS_PREVIEW_BUNDLE_ID. Changing daemon behavior may require a deliberate restart, which can end running terminal processes.