Osaurus · MLX inference🜂 entheai · agent decomposition🜂 MEM8 · wave memory🜂 ayeOS · ternary daemon🜂 MLX-QUANT · Metal kernels🜂 HF Accelerate · MPS training🜂 hf-mount · repo filesystems🜂 BitNet b1.58 · {-1, 0, +1}🜂 Project Zero · C99 CPU ternary🜂 MiroFish · swarm prediction🜂

01 — capabilities

Engineered for on-device excellence

Real native macOS app performance with complete data sovereignty and instant accessibility.

⚡

Apple Silicon Native

Runs seamlessly on M1/M2/M3/M4 unified memory architectures via Osaurus engine for maximum throughput.

🤗

Live HF Hub Search

Instant model discovery across Hugging Face Hub repositories with model metadata, tags, and pull triggers.

🜂

Dual Window & Agent UI

Work from a full workspace window or summon the quick prompt agent anytime directly from your macOS Menu Bar.

🧠

MoE Optimizer Layer

Intent classification (Code, Math, Summary, Creative) that dynamically routes prompts to specialized local models with expert system prompts.

♾️

MEM8 Wave Memory

Wave interference recall with entheai-aligned frequency-band classification. On-device, deterministic, zero network — the same algorithm as the Rust memory-pp NativeMesh.

🔺

ayeOS Ternary Daemon

Deterministic LINOSV-seeded ternary matrices at 12.80× compression. MEMNET protocol daemon bridged to MLX-QUANT Metal kernels for BitNet b1.58 inference.

🧬

entheai Agent

Spawn the entheai agent as a subprocess for fan-out decomposition, codebase analysis, and project-wide operations — all from the Ecosystem tab.

🖥️

Project Zero · CPU Ternary

A third Run backend — shifulegend/project-zero, a dependency-free C99 engine serving {-1,0,+1} inference locally on :8090. The same law, no GPU. wiring ↗

🧠

MiroFish · Swarm Prediction

Connect to a local MiroFish — a swarm-intelligence engine that simulates thousands of agents over seed material, then returns a prediction report. Backend :5001, over HTTP. AGPL stays a separate process. wiring ↗

🎙️

Voice · Sidecar Architecture

VoiceBackend protocol with swappable Apple-native or 8b-native Rust sidecars (kokoro-tiny TTS, liquid-rust STT). On-device, zero telemetry.

02 — data flow

One honest pipeline, fully on-device

Browse → pull → recall → route → infer → chat. Hover a stage to see what moves through it — no stage touches a cloud.

Hover a stage to see what moves through it.

03 — live demo

The MoE optimizer, in your browser

Type a prompt — or pick an example — and watch the on-device classifier pick a domain expert and a local model. This is the same logic MoEOptimizer.swift runs inside the app.

prompt

🧠 General

—

recommended modelany active Osaurus model

system framingconcise, high-throughput general assistant

04 — architecture

Clean separation, all the way down

A thin SwiftUI shell over engines that own the heavy work.

100% Private

Your weights, your memory, your Mac

hf.app acts as an honest interface layer. It never embeds bulky weights or runs heavy background telemetry. Everything heavy is executed on-device by Osaurus on localhost:1337.

✓ Full offline functionality once models are pulled
✓ macOS Keychain integration for Hugging Face tokens
✓ Sandboxed network client architecture

Clean Separation

Data flow & architecture

Browse models on Hugging Face Hub → pull into Osaurus → MEM8 wave recall → MoE auto-route → ayeOS ternary inference → chat locally. The full 8b-is stack: Osaurus (inference), entheai (agent), MEM8 (wave memory), MLX-QUANT (ternary), ayeOS (daemon).

✓ MoEOptimizer.swift: intent classifier & model router
✓ Memory.swift: MEM8 wave interference recall
✓ Services.swift: HubClient · OsaurusClient · AyeosClient · EntheaiClient
✓ HFMacApp.swift: MainActor @Observable AppState + ProcessManager
✓ Views.swift: SwiftUI WindowGroup + MenuBarExtra + Ecosystem tab

🧠 Intelligent Routing

MoE optimizer layer

Zero-latency prompt intent classification directly inside the Swift app. Automatically detects code, math/reasoning, summarization, or creative prompts and routes them to specialized local models.

✓ Code Expert: Swift, Rust, Python, HTML formatting
✓ Reasoning & Math Expert: step-by-step logic framing
✓ Summarization & Creative Experts: domain system prompts
✓ Dynamic Model Router: matches active Osaurus model capabilities

MoE Optimizer Intent Classification & Routing

Always Accessible

Menu bar agent assistant

Need a fast code snippet, translation, or summary? Hit your menu bar icon anytime to open the quick prompt window without interrupting your workflow.

✓ Lightweight floating popover window
✓ Instant context switching
✓ Shared state with the main window

05 — documentation

Documentation & setup guide

Everything you need to run, build, and extend hf.app on your Mac.

Install in under a minute

1 · Get the app. Download the latest .dmg (v0.12.0), open it, and drag hf.app into Applications. It's Developer-ID signed & notarized, so it opens with no Gatekeeper warning — no xattr dance.

2 · Get the engine. Install Osaurus and start it on localhost:1337. hf.app is the thin front-end; Osaurus owns the weights, MLX, and serving.

3 · Pull & run. Pull a model in Osaurus (Llama, Qwen, Phi…), then hit Refresh in the Run tab of hf.app. Real tokens/sec, fully on-device — your HF token stays in the macOS Keychain.

Run from source (developers)

Needs the Xcode Command Line Tools. Builds with SwiftPM — no Xcode project required:

BASH

git clone https://github.com/8b-is/hf-mac.git
cd hf-mac
swift run

Swift codebase — `Sources/HFMac/`

Ten single-responsibility files, ~1,600 lines total. hf.app drives Osaurus for inference, entheai for agent tasks, and ayeOS for ternary inference — it never bundles weights or a model runtime. Read by layer:

Entry & Router

HFMacApp.swift @main App — WindowGroup + MenuBarExtra, holding the @Observable AppState the whole UI reads. 186 loc

MoEOptimizer.swift Mixture of Experts layer — prompt intent classifier (ExpertDomain) and intelligent local model auto-router. 90 loc

Data & services

Memory.swift MEM8 wave recall — port of MEM8 from smart-tree's wave.rs to native Swift. Frequency-band encoding + interference scoring. Same algorithm as entheai's Rust mesh.rs wave_scorer. On-device, deterministic. 140 loc

VoiceEngine.swift VoiceBackend protocol — Apple-native AVSpeechSynthesizer/SFSpeechRecognizer plus ProcessVoiceBackend for 8b-native Rust sidecars (kokoro-tiny TTS, liquid-rust STT). Swappable at runtime. 200 loc

Services.swift HubClient (HF Hub REST), OsaurusClient (OpenAI /v1 chat), ProjectZeroClient (local C99 ternary, :8090), AyeosClient (MEMNET UNIX socket), EntheaiClient (subprocess agent), Toolchain (PATH resolver), ProcessManager (lifecycle). 430 loc

OfflineStore.swift Offline content on disk — full static-Space snapshots (playable with no network) and cached article HTML, under Application Support. 50 loc

Keychain.swift Wrapper for the two secrets — the HF token and the optional Osaurus key. Never written to disk in the clear. 37 loc

Interface

Views.swift Six tabs — Spaces, Articles, Models, Run, Yours, Ecosystem — plus menu-bar agent and settings. 780 loc

WebView.swift SpaceWebView — embeds a live Hugging Face Space (*.hf.space) so quantum games, Gradio, and static apps run on the desktop; caches visited assets. 40 loc

Theme.swift The pocoo.vaked.dev palette — near-black-blue ground, cyan accent, mono type — over native macOS glass materials. 40 loc

Mixture of Experts (MoE) intent classifier & router

The MoEOptimizer module (Sources/HFMac/MoEOptimizer.swift) performs on-device intent classification before sending prompts to your local Osaurus server. It evaluates user input across five domain experts:

⚡ Code Expert: injects software engineering system prompts and routes to coder/qwen models.
📐 Reasoning & Math Expert: formats step-by-step reasoning instructions and routes to reasoning/r1 models.
📝 Summarization Expert: formats actionable bullet-point extraction instructions.
🎨 Creative Writing Expert: enhances creative storytelling and drafting prompts.
🧠 General Expert: high-throughput, concise general responses.

How it works

SWIFT — MoEOptimizer.swift

let route = MoEOptimizer.optimize(
    prompt: text,
    chatHistory: chat,
    availableModels: osaurusModels
)
// route.domain → classified ExpertDomain
// route.recommendedModelID → auto-routed Osaurus model
// route.formattedMessages → messages with expert system framing

Keychain & entitlements security

The app holds two secrets — your Hugging Face token and the optional Osaurus key — in the system Keychain via macOS Security.framework (kSecClassGenericPassword, service hf.app). Never written to disk in the clear. Full policy: SECURITY.md.

Two entitlement sets, on purpose: the Developer-ID build is sandbox-free (it execs local companions — entheai, ayeosd, hf-mount, python3), while the App Store build keeps the sandbox. A guard (scripts/check-entitlements.sh) probes both through AMFI before signing.

ENTITLEMENTS

<!-- Developer-ID / OSS build: NO sandbox — it execs local companions.
     Packaging/hf-mac-devid.entitlements -->
<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict/></plist>

<!-- Mac App Store build: sandboxed (Packaging/hf-mac.entitlements) -->
<dict>
    <key>com.apple.security.app-sandbox</key>
    <true/>
    <key>com.apple.security.network.client</key>
    <true/>
</dict>

Build & run in Xcode

The Xcode project is generated from project.yml (XcodeGen) over the same Sources/HFMac — the .xcodeproj is git-ignored, so project.yml is the source of truth. Generate it, then open:

BASH

brew install xcodegen     # once
xcodegen generate         # writes HFMac.xcodeproj
open HFMac.xcodeproj       # ⌘R to run · Product ▸ Archive to package

Press ⌘R to run, or Product ▸ Archive for a release build. The shared HFMac scheme is what both Xcode and Xcode Cloud use. Signing is automatic (Team 7CFQYBX575); for an unsigned local build add CODE_SIGNING_ALLOWED=NO to an xcodebuild invocation.

Ship it — notarized DMG & the Mac App Store

Two tracks, one codebase. Full runbook: APP_STORE.md · PUBLISHING.md.

① Developer-ID DMG (OSS / direct download). Push a v* tag and GitHub Actions builds → Developer-ID signs → notarizes + staples → cuts a Release. Runs on Blacksmith Apple-Silicon runners.

RELEASE — TAG TO SHIP

git tag v0.12.0
git push --tags      # → notarized .dmg on Releases

② Mac App Store / TestFlight via Xcode Cloud with Apple-managed signing — no manual certs. The app record is live: hf.app, Apple ID 6794829098. Open the generated project, choose Product ▸ Xcode Cloud, pick the HFMac scheme, and archive → TestFlight. The ci_scripts/ hooks regenerate the project and stamp the build number automatically.

Engineered for on-device excellence

Apple Silicon Native

Live HF Hub Search

Dual Window & Agent UI

MoE Optimizer Layer

MEM8 Wave Memory

ayeOS Ternary Daemon

entheai Agent

Project Zero · CPU Ternary

MiroFish · Swarm Prediction

Voice · Sidecar Architecture

One honest pipeline, fully on-device

The MoE optimizer, in your browser

Clean separation, all the way down

Your weights, your memory, your Mac

Data flow & architecture

MoE optimizer layer

Menu bar agent assistant

Documentation & setup guide

Install in under a minute

Run from source (developers)

Swift codebase — Sources/HFMac/

Mixture of Experts (MoE) intent classifier & router

How it works

Keychain & entitlements security

Build & run in Xcode

Ship it — notarized DMG & the Mac App Store

Swift codebase — `Sources/HFMac/`