Threadling

Threadling is a native macOS companion that holds your mental resume point before an interruption. Press Command–Shift–Space, write where you were and what comes next, then return through the creature’s backpack.

Threadling cannot connect to the internet. Everything it remembers stays encrypted on this Mac. It never uploads notes, screenshots, audio, app activity, attachments, or usage statistics.

Opening an attached web link deliberately hands that link to the chosen browser; resulting browser traffic belongs to the browser, not Threadling.

Implemented v1 surface

• Global capture shortcut and compact keyboard-first panel
• Frontmost app context, notes, next action, project, files, links, screenshots, and optional local reminders
• Strict on-device speech recognition with no cloud fallback and no audio files
• Ten-state pixel companion, backpack popover, full searchable library, completion/archive/recovery states
• AES-GCM record, screenshot, bookmark, and password-derived backup encryption
• Device-only, non-synchronizing Keychain master key
• Security-scoped file bookmarks and explicit application/file/link resume
• Unlimited active threads for every user
• App Sandbox without network client/server entitlements, no third-party runtime code, privacy manifest, and source/release privacy checks

Build and test

Requirements: Xcode 16+, macOS 14+.

swift build
swift test
Scripts/verify-zero-network.sh

Open Threadling.xcodeproj and run the Threadling scheme for Xcode development. Do not run the Swift Package executable: it is retained for command-line builds/tests but is not a macOS .app bundle and therefore cannot host notification or privacy permissions. Regenerate the project after adding source files with ruby Scripts/generate-xcode-project.rb.

The Xcode Debug target is signed with the local Apple Development team and builds as Threadling Dev.app, using com.threadling.app.debug and separate encrypted storage.

For a directly launched local .app, use a stable Apple Development identity:

THREADLING_LOCAL_SIGNING_IDENTITY="Apple Development: Your Name (TEAMID)" \
  Scripts/build-local-app.sh

This creates dist/Threadling Local.app with bundle ID com.threadling.app.local and separate encrypted storage. Grant Screen Recording once to this app. Rebuilds signed by the same identity retain their macOS privacy and Keychain identity.

For a customer distribution, install a Developer ID Application certificate and save App Store Connect notarization credentials with notarytool store-credentials. Then run:

THREADLING_SIGNING_IDENTITY="Developer ID Application: Your Company (TEAMID)" \
THREADLING_NOTARY_PROFILE="threadling-notary" \
  Scripts/build-distribution.sh

This creates a Developer ID-signed, notarized, stapled dist/Threadling.zip. The production build deliberately rejects missing, ad-hoc, and Apple Development identities. Scripts/verify-release.sh also rejects an unsigned or unnotarized app.

Prepare a Developer ID distribution certificate

Apple requires Apple Developer Program membership and an Account Holder role to create this certificate. In Certificates, Identifiers & Profiles, create a certificate under Software → Developer ID → Developer ID Application. Create a certificate signing request first in Keychain Access: Certificate Assistant → Request a Certificate From a Certificate Authority, select Saved to disk, then upload that .certSigningRequest file. Download the resulting .cer and double-click it to install it in the login Keychain.

Confirm that macOS can see the installed identity:

security find-identity -v -p codesigning

For notarization, create an app-specific password for your Apple ID, then store it in the local Keychain without putting it in a script:

xcrun notarytool store-credentials "threadling-notary" \
  --apple-id "you@example.com" \
  --team-id "YOUR_TEAM_ID"

The command asks for the app-specific password and validates it. Finally, use the exact Developer ID Application name returned by security find-identity as THREADLING_SIGNING_IDENTITY in the distribution command above. This Apple code signing and notarization is required for a trusted downloadable Mac app; it is unrelated to donations or payments.

The first Screen Recording request is expected only when a user deliberately invokes screenshot capture. A correctly signed update retains that authorization. A fresh install creates its own device-only encryption key without asking for a Keychain password; correctly signed updates continue to access that same key without prompting.

Threadling Dev, Threadling Local, and production Threadling intentionally use separate bundle IDs, Keychain services, Application Support folders, and macOS privacy permissions.

Threadling is free. Donations happen only through the website; the installed app has no payment, account, or donation code.

Privacy boundary

The guarantee covers Threadling’s own process and storage. It does not protect against root access, malware, another person using an unlocked account, or traffic caused after the user opens a link in another application.