Skip to content

Install the Hadron macOS menu bar app

Hadron for Mac is a native menu bar app. Once you sign in, it gives you quick, always-available access to:

  • Memories — the memories you can read.
  • Tasks — runnable task nodes.
  • Find — keyword search across the knowledge graph.

Each row has an Open in portal button that deep-links to the entity on hadronmemory.com. The app lives only in the menu bar — it has no Dock icon.

The source lives at hadron-memory/hadron-macapp. There are no prebuilt release binaries yet, so you build it from source with the Swift toolchain — it's a two-command build.

Requirements

  • macOS 14 (Sonoma) or later.

  • The Swift 6 toolchain. Either install Xcode from the App Store, or the Command Line Tools:

    xcode-select --install

    Verify:

    swift --version

Get the source

git clone https://github.com/hadron-memory/hadron-macapp.git
cd hadron-macapp

Install

Choose one of the two paths.

Build a double-clickable HadronMenuBar.app and move it into /Applications:

Scripts/make-app.sh
mv dist/HadronMenuBar.app /Applications/
open /Applications/HadronMenuBar.app

Scripts/make-app.sh does a release build, assembles the bundle (with LSUIElement so it stays menu-bar-only), and ad-hoc code-signs it.

Gatekeeper on an ad-hoc-signed app

The bundle is ad-hoc signed, not notarized. On first launch macOS may refuse to open it. If so, right-click the app in Finder and choose Open, then confirm — or clear the quarantine attribute:

xattr -dr com.apple.quarantine /Applications/HadronMenuBar.app

To try it without producing a bundle, run it straight from the checkout:

swift run HadronMenuBar

The app keeps running until you quit it. This is the fastest way to try the app, but it stays tied to the terminal session and the source checkout.

First run and sign in

  1. Look for the brain icon in the menu bar (top-right of the screen). The app has no Dock icon and no window in the app switcher — it is entirely in the menu bar.
  2. Click the icon, then click Sign in with Hadron.
  3. A secure browser sheet opens and runs the standard OAuth sign-in — sign in (via GitHub) and approve access. When it finishes, the sheet closes and the panel switches to the signed-in view showing your handle.

Sign-in uses the platform's OAuth 2.1 flow with PKCE. The issued key is stored in your macOS Keychain and never written to disk in plaintext. There is no separate API key to copy or paste.

Use it

The signed-in panel has three tabs:

  • Memories — every memory you can read, with its class and URN.
  • Tasks — runnable task nodes, each showing its loc and owning memory.
  • Find — type at least two characters to search node names, locs, descriptions, and tags. Results update as you type.

Click Open in portal on any row to open that memory or node in the web portal.

Use Refresh in the header to reload memories and tasks, Sign Out to remove the key from your Keychain, or Quit to close the app.

Troubleshooting

No icon in the menu bar. The app is running but the menu bar is full, or the launch failed. Confirm it's running:

pgrep -x HadronMenuBar

If nothing prints, launch it again (open /Applications/HadronMenuBar.app or swift run HadronMenuBar). If it prints a PID but you don't see the icon, the menu bar has run out of room — quit some other menu bar apps.

"Your session expired." The stored key was revoked or is no longer valid. The app drops back to the sign-in screen; click Sign in with Hadron again. You can review and revoke the keys tied to your account any time from the Hadron portal.

The build fails. Make sure swift --version reports a Swift 6 toolchain and that you're on macOS 14 or later. Re-run swift build from the repo root to see the full compiler output.

Next steps