Build from source

Building Overterm takes three commands after the clone. The first two are slow and only run once: they compile the terminal core and the syntax grammars into frameworks that then sit in Frameworks/ untouched.

Check Requirements first — the Xcode version in particular is worth getting right before a long build.

1. Get the pinned toolchain

The build needs a specific Zig to compile Ghostty. mise installs it from the pinned version in mise.toml:

git clone https://github.com/Overcraft-hq/overterm.git
cd overterm
mise trust && mise install

2. Build the two frameworks

make ghosttykit   # libghostty from Ghostty v1.3.1 — about two minutes
make treesitter   # tree-sitter plus Helix's grammar queries — about one

make ghosttykit clones Ghostty at a pinned tag and checks its commit hash before building. A moved tag is treated as a supply-chain surprise, not something to build through, so a hash mismatch stops the build rather than warning.

3. Build and install the app

make install

This builds Overterm.app and copies it to /Applications, then refreshes Launch Services so Finder’s Open With menu and the New Overterm Tab Here service see the new build.

To run it without installing:

make run

Signing, and why it matters for your keychain

make install re-signs the app with a code-signing identity it finds in your keychain, falling back to an ad-hoc signature.

The fallback has a cost worth knowing about. An ad-hoc signature changes on every build, so macOS treats each build as a different application — and the login keychain asks again, every time, whether “Overterm” may use your confidential information. Set a stable identity and the prompts stop:

make install SIGN_IDENTITY="Apple Development: you@example.com (XXXXXXXXXX)"

security find-identity -v -p codesigning lists what you have.

Every target

Target	What it does
make ghosttykit	Builds GhosttyKit.xcframework from the pinned Ghostty
make treesitter	Builds TreeSitterKit.xcframework and the grammar queries
make build	Compiles the app
make run	Builds and launches it from the build directory
make install	Builds and copies it to /Applications
make app / make dmg	Produces the bundle, and the disk image around it
make test	The unit and integration suites
make e2e	The end-to-end suite
make icon / make themes	Regenerates the app icon and the bundled themes
make hooks	Installs the git hooks that enforce the version bump
make clean	Removes build output and the generated project

Keeping a build current

make install on a fresh checkout is the whole update. The two framework targets only need running again when the pinned Ghostty or the grammar revisions move, which the changelog says when it happens — see Versioning.

A build you made yourself never sees the in-app update check: that one downloads a release disk image, and you already have something newer.