Build Coincide from source

Requirements

• macOS 26 or later
• Xcode 27 or later
• XcodeGen, which generates the Xcode project from project.yml
• At least one agent CLI, installed and signed in, to try your build (see the agents)

Building

brew install xcodegen
git clone https://github.com/apoorvdarshan/coincide.git
cd coincide
xcodegen generate
open Coincide.xcodeproj

Then build and run the Coincide scheme in Xcode. A few things happen along the way:

• The project file isn’t checked in. Coincide.xcodeproj is generated, so change targets, settings and packages in project.yml, not in Xcode’s project settings. Run xcodegen generate again after editing it, after adding or removing source files, and before building a Release you’ll install: it also sets the build number to the number of commits in your history, so macOS sees each installed build as new.
• Cua Driver is downloaded once. xcodegen generate first runs scripts/fetch-cua-driver.sh, which downloads the pinned release of Cua Driver that Computer Use bundles, checks its checksum and Cua AI’s Developer ID signature, and puts it in the gitignored Vendor/ folder. The download is cached in ~/Library/Caches/Coincide, so later runs work offline.
• SwiftTerm runs a build plug-in. It generates Swift from its own terminfo source. Xcode asks once to trust it; choose Trust & Enable. On the command line, pass -skipPackagePluginValidation to xcodebuild.

Coincide has two package dependencies, SwiftTerm (the terminal) and WhisperKit (Whisper dictation, with no bundled models).

The Debug app

Debug builds, whether from Xcode, the tests or an agent, are a separate app called Coincide Debug, so they never touch your installed Coincide:

Set COINCIDE_DATA_DIR to run a build against a scratch folder instead. Xcode registers every app it builds with Launch Services, and macOS can pick any registered copy for a notification’s icon or click. When you’re done with a build you won’t install, unregister it:

scripts/unregister-builds.sh ~/Library/Developer/Xcode/DerivedData/<folder>

Signing your builds

Builds are signed ad hoc by default, as in CI. That works, but every build gets a new identity, so macOS asks again for permissions such as access to a protected folder your agent configuration lives in. To keep your answers, sign with your own identity: create a gitignored Local.xcconfig in the repository root, as Signing.xcconfig describes, and run xcodegen generate.

// Local.xcconfig
CODE_SIGN_IDENTITY = Developer ID Application
DEVELOPMENT_TEAM = ABCDE12345

Some features need more than a signature:

• The background agent host needs a Developer ID signature; ad-hoc builds run agents in the app.
• The in-app updater installs updates only into a verified Developer ID build.
• Lock-screen alerts for Coincide Remote and passkeys in the browser need entitlements with a matching provisioning profile; Signing.xcconfig explains the steps. Without them the app simply leaves those features out.

Tests

The unit tests use Swift Testing and run in CI on every pull request. To run them yourself, as CI does:

xcodebuild -project Coincide.xcodeproj -scheme Coincide -skipPackagePluginValidation test

Live provider tests drive the real agent CLIs with your own accounts and spend a little of your quota, so they run only when you set TEST_RUNNER_COINCIDE_LIVE_TESTS=1. The fuzzers for Coincide’s parsers live in Fuzz/.

Contributing

Read CONTRIBUTING.md before opening a pull request: it covers the project layout, code style, tests, user-facing text and the pull request checklist. Changed text needs translating too; see Translations. Releases are built, signed and notarized by GitHub Actions from a version tag, as docs/releasing.md describes.