Guide - HTID

Requirements Build Run the client The menu Launch arguments Menu bar app Fpbootd How it works Limitations

Requirements

macOS 14 Sonoma or later (macOS 15 Sequoia or later recommended). Older versions get zero support.
OpenCore v1.0.6 or later. v1.0.5 and older are not supported.
Xcode Command Line Tools: xcode-select --install
Homebrew, then brew install libusb openssl@3 innoextract
Accessibility permission for the daemon. The deploy step handles this for you.
Your sensor must be enabled in your USBMap so it is powered. Check System Information, USB, for your sensor's VID:PID.

Heads up: openssl@3 is scheduled to be deprecated on November 1st 2026, but it should keep working.

1. Build

git clone https://github.com/hackintosh-user/hack-touchid.git
cd hack-touchid
chmod +x prep_and_build.sh
./prep_and_build.sh

This produces the client and each sensor's daemon and support files.

2. Run the client

sudo ./hack-touchid

The first launch shows verbose output. Skip it with --q or --quiet. After the first launch the client adds itself to your $PATH, so from any new terminal you can just run:

sudo hack-touchid

3. Use the menu

Actions
[1] Enroll a Finger
[2] Verify Fingerprint Match [Score / x ]
[3] Deploy Authentication Services
[C] View Fingerprint (capture preview, nothing saved)
[P] (Metallica MIS only) Pair
[U] (UPEK 147e:2016 only) capture .pgm
[B] Capture (experimental, Metallica MIS only)
[FP] Fpbootd, Pre-Login Auth (coming soon)

Utilities
[D] Diagnose (generate a report for troubleshooting)
[S] Settings
[A] About
[X] Uninstall
[Q] Quit

Enroll a finger [1]. Captures several swipes and stores them as a named template on the encrypted volume. Repeat for as many fingers as you like. Verification uses best match wins.
Verify [2]. A standalone test of capture and matching, independent of the daemon. Use it to confirm everything works before deploying.
Deploy [3]. Rebuilds the daemon, installs it as a per-user LaunchAgent, re-signs it, regenerates its Accessibility grant, and installs a narrowly scoped sudoers rule so it can reach the USB device. Re-run on every deploy so the daemon is never stale.

Once deployed, the daemon runs in the background. At the lock screen or a System Settings authentication sheet it asks for a swipe and, on a match, types the stored password.

Launch arguments

Argument	What it does
`--q` / `--quiet`	Launch without the verbose boot output.
`--deploy-agent`	Run [3] Deploy without entering the client. The menu bar app also uses it after a macOS update.
`--diag-pid`	Run the [D] Diagnose steps without launching the client.
`--check-updates`	Check for updates without launching the client. If there is one, it shows the [A] Show changelog / [Y] Download and install / [N] Cancel prompt.
`--menu-updater`	Check for updates and install one right away, with no prompts. The menu bar app's Update Client button runs this in a terminal.
`--debug`	Print every log line for easier debugging.

This list changes over time. New arguments are announced in the changelog.

Menu bar app (optional)

The daemon works the same with or without it. It needs macOS 14 Sonoma or later.

Download the pre-compiled app from the Releases page, or build it:

cd Hackintosh-TouchID-Menubar
chmod +x build_menubar_app.sh
./build_menubar_app.sh
open "build/Hackintosh Touch-ID.app"

First launch is blocked by Gatekeeper because the app is ad-hoc signed. Right-click, Open, Open again, or run xattr -cr "Hackintosh Touch-ID.app".
The daemon needs a small patch to send events to the app. See the daemon patch README.
For useful notifications, set System Settings, Notifications, Show Previews to Always.
Pause and resume is global, it affects every recognized prompt at once.
Swipe notifications are cleared from Notification Center automatically after each swipe, so they do not pile up.

Swipe to Lock (macOS Tahoe only)

macOS 26 Tahoe only, and VFS5011 sensors only. The menu item does not appear on earlier macOS versions, and the daemon ignores the setting there.

Choose Enable Swipe to Lock in the menu bar app. The sensor lights up, and one swipe locks the screen (Ctrl+Cmd+Q). Choose Disable Swipe to Lock to turn it off.
It never matches a finger or types a password for the lock. It steps aside for the real lock screen and padlock prompts, then arms again.
The setting is remembered across daemon restarts and reboots. Update the daemon together with the app.
The daemon needs Accessibility access to send the lock keystroke.
The sensor stays lit while it is on. The client's Enroll and Verify cannot open the sensor meanwhile, so turn Swipe to Lock off first.
It detects that a swipe happened, not its direction.

Fpbootd: pre-login authentication

Fpbootd is an experimental effort to use your fingerprint before you have logged in to macOS. Today HTID only works after login, at the lock screen and in authentication prompts.

Not usable yet. This is early research, with no release date.

Current state

Early spike code is committed on the active-development branch.
The [FP] entry in the client menu is a placeholder. It does nothing yet.
Cold boot sign-in is not supported. See Limitations.

Progress is announced in the changelog.

How it works

Capture

The raw USB protocol is implemented directly against libusb with no Linux driver stack.

Matching

NIST's mindtct extracts minutiae and bozorth3 scores matches, both compiled in.

Storage

Templates and the password sit on an encrypted APFS volume. Its passphrase is in the System keychain.

Detection

The daemon watches the focused UI element through the Accessibility APIs. It patches no system process.

Privilege model

Runs as the console user and only escalates to root, via a scoped sudoers rule, for USB access. Not a system LaunchDaemon.

Limitations

macOS only, and only macOS 14 Sonoma or later. On Linux, use the libfprint driver directly.
Swipe to Lock works only on macOS 26 Tahoe with a VFS5011 sensor.
No PAM module for sudo in a terminal yet. It is planned, but it is unknown whether modern macOS allows it.
Ad-hoc code signing only. No notarization or Developer ID.
Cold boot sign-in is not supported. macOS does not allow this level of access at the login window before a user has logged in. It could take months or years.