- Swift 95.1%
- Shell 4.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .github/workflows | ||
| assets/images | ||
| ci_scripts | ||
| dist | ||
| docs | ||
| Packaging | ||
| scripts | ||
| Sources/HFMac | ||
| Tests | ||
| .gitignore | ||
| APP_STORE.md | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| LANGFLUSE.md | ||
| LICENSE | ||
| Package.swift | ||
| project.yml | ||
| PUBLISHING.md | ||
| README.md | ||
| ROADMAP.md | ||
| SECURITY.md | ||
🜂 HF-MAC{-1,0,+1} — Native macOS Hugging Face Client
Browse the Hugging Face Hub, run models locally on Apple Silicon via Osaurus, and chat from a real workspace window or a menu-bar quick agent. HF-MAC is the thin, honest native front-end — the unified macOS surface for the 8b-is stack: Osaurus (inference), entheai (agent), MEM8 (wave memory), MLX-QUANT (ternary Metal kernels), ayeOS (ternary daemon), Project Zero (CPU ternary, C99), MiroFish (swarm prediction), MOE-ptimizer (context proxy), FLUG-OS (packet-wave sampler), HF Accelerate (MPS training), and hf-mount (repo filesystem).
🌐 Official Web Site & Documentation: https://8b-is.github.io/hf-mac/
📑 Table of Contents
- Vision & Philosophy
- Key Features
- System Requirements & Memory Guide
- Architecture & Data Flow
- Codebase Structure
- Quick Start
- Osaurus Companion Setup
- Project Zero Companion Setup
- MiroFish Companion Setup
- Security & Data Sovereignty
- Building & Distribution
- Contributing & Community
- License
🜂 Vision & Philosophy
ahogy a dolgok vannak — on-device, private, real tokens/sec, no fake states.
Most AI desktop applications suffer from bloated electron wrappers, bundled Python environments, or secret telemetry scripts. hf.app was built with a different philosophy:
- Honest Front-End Architecture: The native Swift application handles user interaction, Hugging Face Hub discovery, and macOS UI integration. It never embeds MLX or Python runtimes directly.
- Dedicated Engine Separation: Local model execution, weights caching, and MLX quantization are delegated entirely to Osaurus — an optimized local inference engine running on
localhost:1337. - Data Sovereignty: Your prompts, conversations, and downloaded weights stay on your machine. Zero cloud telemetry.
✨ Key Features
| Feature | Description |
|---|---|
| ⚡ Apple Silicon Native | Built with pure Swift 5.9 and SwiftUI for macOS 14.0+, leveraging M1/M2/M3/M4 unified memory for maximum token throughput. |
| 🤗 Live HF Hub Explorer | Search millions of open-weight models directly from Hugging Face REST APIs with live metadata, model tags, and pull triggers. |
| 🜂 Dual Native macOS UI | Work in a standard desktop application window (WindowGroup) or invoke the lightweight menu-bar quick assistant (MenuBarExtra) anytime. |
| 🧠 MoE Optimizer Layer | Automatically classifies prompt intent (Code, Math & Reasoning, Summarization, Creative) and routes to specialized local models with expert system prompts. |
| 🔐 Keychain Token Isolation | Securely encrypt and store Hugging Face User Access Tokens in the system macOS Keychain using Security.framework. |
| 🌊 MEM8 Wave Memory | On-device wave interference recall — MEM8 frequency-band classification with entheai-aligned scoring. Zero network. |
| 🔺 ayeOS Ternary Ready | ModelSpeed badges ternary matrices at 12.80× compression via ayeOS MEMNET daemon. |
| 🖥️ Project Zero (CPU) | A third Run backend — a dependency-free C99 ternary engine (shifulegend/project-zero) served locally on :8090. The same {-1,0,+1} law, no GPU. See docs/project-zero.md. |
| 🜂 Local Liberty Models | The sibling Strix Halo story — the halogen MoE, the quantize → abliterate → liberate → projectZeroify recipe, and the uncensored builds in the wild. See docs/liberty-models.md. |
| 🧠 entheai Agent | Spawn entheai subprocess for fan-out decomposition, code analysis, project-wide ops — Ecosystem tab. |
| 🜂 Ecosystem Tab | Unified dashboard: Osaurus · entheai · ayeOS · MEM8 · MLX-QUANT — all status at a glance. |
| Offline First | Once local models are pulled into Osaurus, chat and prompt inference operate completely offline with no network requirement. |
| HF Storage Buckets | Native bucket management — create, sync, and stream training corpora with Xet dedup and the built-in CDN (hf buckets, hf sync). |
| quantal-ternary ready | The constellation's 0.5B BitNet b1.58 ternary model (masked val 0.5597) runs through the MLX-QUANT + ayeOS stack — 168 matrices, offline in Rust. |
💻 System Requirements & Memory Guide
Minimum Requirements
- Operating System: macOS 14.0 (Sonoma) or later.
- Processor: Apple Silicon (M1/M2/M3/M4) or Intel Mac with dedicated Metal GPU.
- Local Engine: Osaurus running on
localhost:1337.
Recommended Memory Allocation for Local Models
| Model Size | Recommended RAM | Suggested Quantization | Example Models |
|---|---|---|---|
| 3B – 7B Parameters | 8 GB – 16 GB | 4-bit / 8-bit MLX | Llama 3 8B, Phi-3-Mini, Mistral 7B |
| 8B – 14B Parameters | 16 GB – 32 GB | 4-bit MLX | Qwen 2.5 14B, Gemma 2 9B |
| 30B – 70B Parameters | 36 GB – 128 GB | 4-bit / 6-bit MLX | Llama 3.3 70B, Qwen 2.5 32B |
🏗️ Architecture & Data Flow
The system loop follows a clear 6-step pipeline:
Browse HF Hub → Pull to Osaurus → MoE Auto-Route → MEM8 Recall → ayeOS Ternary → Run & Chat (Private)
- Browse:
HubClientqueries the Hugging Face REST API (api-inference.huggingface.co) for model cards, tags, and creator metadata. - Pull: Model weights are downloaded and cached by Osaurus into unified memory.
- MoE Optimize:
MoEOptimizerclassifies prompt intent into domain experts (Code, Reasoning, Summary, Creative) and selects the best local model. - MEM8 Recall:
EntheaiMemoryretrieves relevant past spans via wave interference scoring — frequency proximity × amplitude × phase alignment. - ayeOS Ternary: Ternary models (BitNet b1.58, MLX-QUANT) route through ayeOS's
{n+-1-<△>}inference daemon — deterministic LINOSV-seeded matrices, block-sparse matmul at 12.80× compression.ModelSpeed.ternarybadges them instantly. - Run & Chat:
OsaurusClientstreams OpenAI-compatible/v1/chat/completionsSSE to SwiftUI glass components.
📂 Codebase Structure
The codebase is organized into clean, single-responsibility Swift modules:
Sources/HFMac/
├── HFMacApp.swift # @main App entry point, WindowGroup & MenuBarExtra setup
├── MoEOptimizer.swift # Mixture of Experts intent classifier & dynamic model router
├── Services.swift # HubClient (HF Hub REST) & OsaurusClient (OpenAI /v1 API)
├── Views.swift # SwiftUI view hierarchy (Browse, Run, Your Models, MenuBar agent)
├── Keychain.swift # Security.framework wrapper for HF tokens
├── Memory.swift # MEM8 wave-based recall engine (on-device, zero network)
├── OfflineStore.swift # Local persistence & cached model state
├── WebView.swift # WKWebView bridge for interactive model cards & Spaces
├── VoiceEngine.swift # On-device TTS/STT (Apple-native, sidecar-ready)
├── ModelSpeed.swift # Model quantization speed classification
└── Theme.swift # Modern macOS dark glass mode tokens & styling constants
Key Modules
MoEOptimizer.swift: Implements domain classification (ExpertDomain) and intelligent expert model routing.Services.swift: ContainsHubClientfor Hugging Face REST search andOsaurusClientfor local OpenAI-compatible endpoint communication.HFMacApp.swift: The main application definition managing reactive@Observable AppState.Views.swift: Defines SwiftUI components for browsing, chatting, model management, and the floating menu-bar quick agent.Keychain.swift: Implements secure OS-level keychain access (dev.peterl.hfmac.token).Memory.swift: MEM8 wave-based recall engine — encodes spans as waves, scores relevance via interference.
🚀 Quick Start
Option A: Pre-built Notarized DMG
Download the latest Developer-ID notarized .dmg release from our Releases Page, open the disk image, and drag HFMac.app to your Applications folder.
Option B: Build & Run from Source
# 1. Clone the repository
git clone https://github.com/8b-is/hf-mac.git
cd hf-mac
# 2. Compile and run with Swift Package Manager
swift run
Or open in Xcode:
open Package.swift
Companion health check
hf.app drives local tools — entheai, ayeosd, hf-mount, python3/accelerate.
See exactly what it resolves and whether the ayeOS daemon is up:
swift run HFMac --check-tools
# companions · ayeOS daemon (over /tmp/ayeosd.sock) · the entheai argv it would run
The Ecosystem tab reports the same found/not-found state; entheai takes a
positional prompt, and ayeosd binds a local UNIX socket (the AyeFire
covenant — no IP listener).
🔌 Osaurus Companion Setup
hf.app relies on Osaurus for local model serving:
- Download and launch Osaurus on your Mac.
- Ensure Osaurus is listening on
http://localhost:1337. - Pull your desired model inside Osaurus (e.g.
llama3:8b). - Click Refresh in the Run tab of
hf.appto instantly sync available local models.
🖥️ Project Zero Companion Setup
Project Zero is the CPU ternary backend — optional, and useful when you want
{-1,0,+1} inference without touching the GPU:
- Build the engine and fetch a 1.58-bit model:
bash scripts/setup-project-zero.sh. - Start it:
~/project-zero/adaptive_ai_engine --model ~/models/*.gguf --server --port 8090. - In
hf.app→ Run, pick Project Zero (CPU) and Refresh.
Full notes: docs/project-zero.md.
🧠 MiroFish Companion Setup
MiroFish is a swarm-intelligence prediction engine — it builds a parallel digital world of thousands of agents from seed material, then returns a prediction report. hf.app connects to it (it does not ship or link it — MiroFish is AGPL-3.0):
- Clone and run it:
git clone https://github.com/666ghj/MiroFish && cd MiroFish && npm run setup:all && npm run dev. - It serves a Flask backend on
:5001and a Vue frontend on:3000. - In
hf.app→ Ecosystem, MiroFish shows connected; Open MiroFish opens the frontend.
Full notes: docs/mirofish.md.
🛡️ Security & Data Sovereignty
- App Sandbox Entitlements: Enforced via
Packaging/hf-mac.entitlements(com.apple.security.app-sandboxandcom.apple.security.network.client). - Zero Telemetry: No tracking cookies, analytics SDKs, or diagnostic logging.
- Keychain Security: Hugging Face access tokens are encrypted in the macOS Keychain.
- See our full
SECURITY.mdpolicy for vulnerability disclosure guidelines.
📦 Building & Distribution
Build targets and notarization processes are documented in PUBLISHING.md:
- Direct Notarized DMG: Automated build via
.github/workflows/release.ymlonv*tag pushes. - Mac App Store: Scaffolded in
.github/workflows/mas.ymlfor sandboxed App Store Connect upload.
🤝 Contributing & Community
Contributions are welcome! Please read our CONTRIBUTING.md guide for details on development setup, Swift style guidelines, and pull request procedures.
- Found a bug? Open an issue on GitHub Issues.
- Security concern? Refer to
SECURITY.md.
📄 License
Distributed under the MIT License. See LICENSE for details.
🜂 ahogy a dolgok vannak — on-device, private, real tokens/sec, no fake states.



