Install

The Mac app comes as a notarized download and a Homebrew cask; the iOS app is built from source.

Requirements

macOS 26 or later.
Xcode 27 (the Swift 6.2 toolchain).
Optional: GNU Emacs, for the features that hand work to it on the Mac (Emacs Lisp code blocks that need full Emacs, Lisp table formulas the built-in interpreter can't run, and export to PDF, LaTeX, ODT and other formats). See Working alongside Emacs and other tools.

The Mac app

With Homebrew

brew tap krz/tap https://gitbay.org/krz/homebrew-tap.git
brew install --cask orgstar

As a download

Download orgstar-<version>.dmg from the releases page, open it, and drag orgstar to Applications. The app is universal (Apple silicon and Intel), signed with a Developer ID and notarized by Apple, so it opens without warnings.

From source

git clone https://gitbay.org/krz/orgstar.git
cd orgstar
scripts/build-app.sh
open .build/app/orgstar.app

scripts/build-app.sh builds a release binary and assembles .build/app/orgstar.app with its Quick Look and Spotlight extensions, signed ad hoc for use on your own Mac. Move it to /Applications to keep it. Pass a version number as the first argument to stamp the bundle (scripts/build-app.sh 1.0.0); the default is 0.1.0.

Once the app has been launched, Finder opens .org files with it, Quick Look shows them formatted, and Spotlight indexes their headings and text.

The iOS app

The iOS app (iOS 26 or later) is built with Xcode from ios/Orgstar.xcodeproj:

Open ios/Orgstar.xcodeproj.
Select the Orgstar iOS target, then Signing & Capabilities, and choose your team. Change the bundle identifiers (sh.krz.orgstar and the three extensions' .share, .quicklook and .widgets) and the App Group (group.sh.krz.orgstar) to ones your team can register.
Choose your iPhone or iPad (or a Simulator) as the destination and Run (⌘R).

On a device, Developer Mode must be on (Settings ▸ Privacy & Security ▸ Developer Mode).

For the Simulator without opening Xcode (this build has no widgets):

scripts/build-ios-app.sh
xcrun simctl install booted .build/ios-app/orgstar.app

See iPhone and iPad for what it does.

Updating

orgstar checks for a new release once a day, after asking on its second launch whether it may; orgstar ▸ Check for Updates… checks now, and Settings ▸ General has the switch. An update downloads, is checked against the key the releases are signed with, and installs when you agree. With Homebrew, brew upgrade --cask orgstar works too; the cask leaves updating to the app otherwise. From source, pull and build again (a build without a Developer ID never checks):

git pull
scripts/build-app.sh

Your settings live in ~/.config/orgstar/ and survive rebuilds.

Uninstalling

Delete orgstar.app, or run brew uninstall --cask orgstar. To remove your settings as well, delete ~/.config/orgstar/ (brew uninstall --zap --cask orgstar does both). Your org files are never stored inside the app.