Zyquo Local icon # Zyquo Local ### Every token stays on your Mac. 🍏⚑ **A legendary native macOS AI chat client that runs large language models 100 % locally on Apple Silicon with [MLX](https://github.com/ml-explore/mlx-swift) β€” no API keys, no cloud, no data ever leaving your machine.**
[![Release](https://img.shields.io/github/v/release/spboucher-ai/zyquo-local?style=for-the-badge&color=17C787&label=Release)](https://github.com/spboucher-ai/zyquo-local/releases/latest) [![Platform](https://img.shields.io/badge/macOS-14.0%2B-blue?style=for-the-badge&logo=apple)](https://github.com/spboucher-ai/zyquo-local/releases/latest) [![Chip](https://img.shields.io/badge/Apple%20Silicon-arm64-orange?style=for-the-badge&logo=apple)](https://support.apple.com/en-us/116943) [![Swift](https://img.shields.io/badge/Swift-6-F05138?style=for-the-badge&logo=swift&logoColor=white)](https://swift.org) [![MLX](https://img.shields.io/badge/Engine-MLX-000000?style=for-the-badge)](https://github.com/ml-explore/mlx-swift)
[![License](https://img.shields.io/github/license/spboucher-ai/zyquo-local?style=for-the-badge&color=4C2BE0)](LICENSE) [![Downloads](https://img.shields.io/github/downloads/spboucher-ai/zyquo-local/total?style=for-the-badge&color=2B6BFF&label=Downloads)](https://github.com/spboucher-ai/zyquo-local/releases) [![Signed & Notarized](https://img.shields.io/badge/Apple-Signed%20%26%20Notarized-success?style=for-the-badge&logo=apple)](https://github.com/spboucher-ai/zyquo-local/releases/latest)
**[⬇️ Download the latest DMG](https://github.com/spboucher-ai/zyquo-local/releases/latest/download/ZyquoLocal.dmg)** Β· Developer ID signed Β· Notarized by Apple Β· Stapled
--- ## πŸ“‘ Table of Contents - [Why Zyquo Local?](#-why-zyquo-local) - [Features](#-features) - [Private, local inference](#-private-local-inference) - [Browse & download models inside the app](#-browse--download-models-inside-the-app) - [A chat experience that respects your hardware](#-a-chat-experience-that-respects-your-hardware) - [Power tools](#-power-tools) - [macOS-native polish](#-macos-native-polish) - [Screenshots](#-screenshots) - [Verified performance](#-verified-performance) - [Installation](#-installation) - [Requirements](#-requirements) - [Usage](#-usage) - [Building from source](#%EF%B8%8F-building-from-source) - [Architecture](#%EF%B8%8F-architecture) - [Roadmap](#-roadmap) - [Contributing](#-contributing) - [License](#-license) - [Author](#-author) --- ## πŸ”’ Why Zyquo Local? Cloud chatbots read your prompts. **Zyquo Local doesn't have a server to send them to.** Inference runs entirely on your Mac's unified memory and GPU through Apple's MLX framework. The only network calls the app ever makes are the ones **you** trigger to download model weights from Hugging Face β€” and even those are resumable, verified, and stored in a folder you control. Everything else β€” every conversation, every token, every system prompt β€” lives in `~/Library/Application Support/ZyquoLocal/` and nowhere else. --- ## ✨ Features ### πŸ” Private, local inference - **100 % on-device generation** via [mlx-swift-lm](https://github.com/ml-explore/mlx-swift-lm) β€” no API keys, no accounts, no telemetry, works fully offline once a model is downloaded. - **57 supported architectures** out of the box: Llama, Qwen 2/3/3.5/3.6, Mistral/Mixtral, Gemma 1–4, Phi-3/4, DeepSeek-V3 distills, gpt-oss, GLM-4, SmolLM3, LFM2, OpenELM, StarCoder2, Granite, and more β€” with a compatibility check *before* you download anything. - **True token streaming** with a live tokens/second ticker, cancellable mid-generation β€” the stop button actually stops the GPU loop. - **Reasoning display**: `…` output from thinking models (DeepSeek-R1 distills, Qwen3 thinking mode, QwQ-class) streams into a collapsible *Thought process* section, parsed incrementally and robust to tags split across token chunks. - **First-class statistics** under every response: `⚑ tokens/sec Β· token count Β· time-to-first-token`, plus peak-memory tracking per generation. - **Multi-turn context management**: KV-cache reuse across turns (no re-prefill), automatic oldest-turn truncation when the context window fills (the system prompt always survives), and a live context-usage bar. - **Verifiable memory hygiene**: one model loaded at a time, explicit Load/Unload, and unloading provably returns memory to the OS (gigabytes β†’ kilobytes, measured via MLX memory APIs). ### 🧲 Browse & download models inside the app - **Live Hugging Face search** without leaving the app: scopes for the curated *Featured* catalog, the `mlx-community` organization, or all MLX-tagged repos; sort by downloads/likes/newest; filter by size class; gated-repo and unsupported-architecture warnings right on the card. - **A hand-picked Featured catalog of 30 models** β€” tiny (Qwen3-0.6B, Llama-3.2-1B, SmolLM3-3B…), mid (Qwen3-8B/14B, Gemma-3-12B, Phi-4, gpt-oss-20b…), large (Mistral-Small-24B, Gemma-3-27B, Qwen3-30B-A3B MoE, Llama-3.3-70B…), coding (Qwen2.5-Coder, Qwen3-Coder-30B-A3B) and reasoning (R1 distills, Qwen3-Thinking) β€” every repo ID and download size verified against the live Hub. - **Industrial-grade download manager**: pause / resume / cancel per model, **HTTP Range resume that survives app restarts**, automatic retry with backoff on transient network drops, 2 parallel file streams, live speed + ETA, atomic `.partial β†’ final` completion, per-file size verification, and a disk-space pre-check before a single byte is fetched. - **RAM verdicts everywhere**: a `MemoryAdvisor` reads *your* Mac's physical memory and stamps every model β€” installed or discoverable β€” with **Fits / Tight / Too large**, so you never download something your machine can't run. - **Model library**: sizes on disk, architecture and quantization badges, context-window length, last-used dates, per-model default generation parameters, Reveal in Finder, and delete-with-reclaimed-space confirmation. - **Optional Hugging Face token** (Settings β†’ Models & Storage, masked input) for gated repos like Llama and Gemma β€” sent exclusively to huggingface.co, stripped from cross-host CDN redirects. ### πŸ’¬ A chat experience that respects your hardware - **Multi-conversation sidebar** with full-text search across titles *and* message content, pinning, renaming, date grouping (Pinned / Today / Yesterday / Previous 7 Days / Older), and per-conversation model badges. - **Per-conversation everything**: model, system prompt, temperature, top-p, repetition penalty, max tokens, and seed β€” with plain-language explanations and app-wide defaults in Settings. - **Model switcher in the chat header**: click the model chip to swap among downloaded models (RAM verdicts included) with inline load progress; each conversation remembers its model. - **Message actions**: copy, edit & resend (rewinds the conversation), regenerate, quote-reply, delete. - **Full Markdown rendering** (swift-markdown): headings, lists, quotes, tables, inline styles β€” and **syntax-highlighted code blocks with one-click copy**. - **Attachments**: drag & drop or attach text files (`txt`, `md`, code, `csv`, `json`…) β€” contents are injected into your message as labeled fenced blocks. - **Auto-titled conversations** using the loaded model itself after the first exchange. - **Onboarding that doesn't waste your time**: first launch offers starter models *sized for your specific Mac* with one-click download and inline progress. ### πŸ›  Power tools - **⚑ Quick Chat** (global `βŒ₯Space`): a Spotlight-style floating panel for one-shot questions to the loaded model, from anywhere in macOS β€” no accessibility permissions needed. - **πŸ†š Compare mode**: run **two models side-by-side** on the same prompt with independent streaming and stats β€” RAM-gated so you can't load a pair your memory can't hold. - **πŸ“š Prompt library**: 56 built-in templates across 8 categories (writing, coding, analysis, learning, productivity, communication, language, creative) with `{{variable}}` placeholders β€” plus your own saved templates. - **🎭 Personas**: reusable system prompt + preferred model + parameter bundles (4 thoughtful built-ins included). - **πŸ“€ Export** any conversation to **Markdown or PDF**; bulk export/import of all conversations as JSON. - **πŸ“Š Live resource footer**: currently loaded model, real-time MLX active-memory readout, and a colored pressure dot. ### 🍎 macOS-native polish - **Real Mac app**: SwiftUI, `NavigationSplitView`, native Settings (6 tabs), translucent sidebar, hover states, snappy popovers, 0.5 pt hairlines β€” designed, not generated. - **Menu bar extra** (toggleable) with loaded-model status, download progress at a glance, and Quick Chat access. - **Keyboard-first**: `⌘N` new chat Β· `⌘K` model switcher Β· `⌘L` library Β· `⌘F` search Β· `βŒ˜β†©` send Β· `β‡§βŒ˜E` export Β· `βŒ₯Space` Quick Chat. - **Light & dark themes** from a strict design-token system (emerald-on-graphite identity), five accent colors, adjustable chat text size with live preview. - **Signed & notarized**: Developer ID, hardened runtime, stapled ticket β€” Gatekeeper installs it without warnings. --- ## πŸ“Έ Screenshots
**Chat β€” streaming, thinking disclosure, per-response stats (dark theme)** Chat in dark mode with thought process disclosure and generation statistics

**Discover β€” the curated catalog with RAM verdicts for *your* Mac** Discover tab with featured models, sizes and memory verdicts

**Library β€” installed models with architecture, quantization and context badges** Installed models with badges and actions
--- ## 🏁 Verified performance Every release is validated by an end-to-end harness (`ZyquoLocal --verify`) that downloads real models through the app's own pipeline, then checks loading, deterministic generation, multi-turn recall, streaming cancellation, and memory release. Measured on an Apple M5 Max (48 GB): | Model | Load | Generate | Multi-turn | Cancel | Unload | tok/s | TTFT | |---|:-:|:-:|:-:|:-:|:-:|--:|--:| | Qwen3-0.6B-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 109.4 | 0.08 s | | Llama-3.2-1B-Instruct-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 222.8 | 0.74 s | | SmolLM3-3B-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 97.4 | 0.11 s | | gemma-3-4b-it-qat-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 58.3 | 1.08 s | | Qwen2.5-Coder-7B-Instruct-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 112.5 | 0.42 s | | DeepSeek-R1-0528-Qwen3-8B-4bit | βœ… | βœ… | βœ… | βœ… | βœ… | 61.3 | 0.08 s | Full methodology and the 30/30 catalog verification: [`docs/VERIFICATION.md`](docs/VERIFICATION.md). --- ## πŸ“¦ Installation 1. **[Download `ZyquoLocal.dmg`](https://github.com/spboucher-ai/zyquo-local/releases/latest/download/ZyquoLocal.dmg)** from the latest release. 2. Open the DMG and drag **Zyquo Local** into **Applications**. 3. Launch it. The app is Developer ID signed and notarized by Apple β€” no Gatekeeper hoops. 4. Pick a starter model sized for your Mac and click **Download**. That's it β€” chat away, even offline. > πŸ’‘ Models are stored in `~/Library/Application Support/ZyquoLocal/Models/` and can be deleted from the in-app Library at any time (the app shows exactly how much space you'll reclaim). --- ## 🧰 Requirements | | Minimum | |---|---| | **Mac** | Apple Silicon (M1 or later) β€” MLX requires it; Intel Macs are not supported | | **macOS** | 14.0 (Sonoma) or later | | **Memory** | 8 GB runs ≀4 B models comfortably Β· 16 GB β†’ 7–14 B Β· 32 GB β†’ 24–32 B Β· 64 GB β†’ 70 B | | **Disk** | 0.35 GB (smallest model) β†’ 40 GB (Llama-3.3-70B); the app pre-checks free space | | **Network** | Only for downloading models; inference is fully offline | --- ## πŸš€ Usage | I want to… | Do this | |---|---| | Get my first model | Launch β†’ pick a starter card β†’ **Download** β†’ it auto-appears in the model chip | | Chat | Type and hit `βŒ˜β†©`; press the stop button to halt generation instantly | | See how a model thinks | Reasoning models stream into the collapsible **Thought process** section | | Switch models | Click the model chip in the header (or `⌘K`) β€” verdicts tell you what fits | | Tune generation | The sliders icon in the input bar (per-conversation) or Settings β†’ Inference (defaults) | | Ask from anywhere | `βŒ₯Space` β€” Quick Chat floats above whatever you're doing | | Race two models | Menu **Model β†’ Compare Models…**, pick two, broadcast one prompt | | Reuse a great prompt | The templates icon in the input bar β€” 56 built-ins with fillable variables | | Share a conversation | Header export menu β†’ Markdown or PDF | | Use gated models (Llama, Gemma) | Settings β†’ Models & Storage β†’ add your Hugging Face token | --- ## πŸ—οΈ Building from source Zyquo Local is plain **Swift Package Manager** β€” no `.xcodeproj`, and the Xcode IDE is never required. Two prerequisites beyond the Command Line Tools: 1. **Apple's Metal Toolchain** on `PATH` β€” MLX compiles its GPU kernels at build time. On a machine with Xcode 26+: `xcodebuild -downloadComponent MetalToolchain`; a standalone `Metal.xctoolchain` on `PATH` also works. 2. **SDK pin** on macOS 27 CLT setups: `SDKROOT=MacOSX26.5.sdk` (SwiftUI macros are Xcode-only plugins in the 27.x CLT SDKs). ```sh git clone https://github.com/spboucher-ai/zyquo-local.git cd zyquo-local make build # debug build make dev # debug bundle (ad-hoc signed) + launch make poc MODEL= PROMPT="Hello" # CLI inference proof-of-concept make icon # regenerate AppIcon.icns from the SVG source make release # Developer ID signed + notarized + stapled app & DMG ``` The full recipe, the Metal-toolchain findings, and the research that pinned every dependency version live in [`docs/BUILD.md`](docs/BUILD.md) and [`docs/MLX-RESEARCH.md`](docs/MLX-RESEARCH.md). --- ## πŸ›οΈ Architecture ``` Sources/ZyquoLocal/ β”œβ”€β”€ App/ @main entry, scenes, CLI modes (--poc, --hub-poc, --verify) β”œβ”€β”€ DesignSystem/ ZyquoTheme β€” every color, font, spacing and radius token β”œβ”€β”€ Models/ Conversation, Message, LocalModel, DownloadTask, Persona β”œβ”€β”€ Engine/ InferenceEngine (actor) Β· ChatSession Β· MemoryAdvisor Β· GenerationParams β”œβ”€β”€ Hub/ HubService Β· DownloadManager Β· FileTransfer Β· ModelStore β”œβ”€β”€ Services/ Persistence Β· ModelCatalog Β· PromptLibrary Β· Personas Β· Export Β· Settings β”œβ”€β”€ ViewModels/ AppModel Β· ChatController (streaming + parser) └── Views/ Chat Β· Library Β· Settings Β· QuickChat Β· Compare Β· Components ``` - **`InferenceEngine` is a Swift actor** β€” all inference behavior lives behind it; states flow `unloaded β†’ loading β†’ ready ⇄ generating`, generation is an `AsyncThrowingStream` of token/stats/finish events, and cancellation genuinely stops the loop. - **Dependencies** (pinned, researched, minimal): `mlx-swift-lm` Β· `swift-transformers` (tokenization) Β· `swift-huggingface` Β· `swift-markdown`. Downloads use a custom `URLSession` transport β€” delegate-backed, chunked, Range-resumable. - **7 300+ lines of Swift 6**, zero compiler warnings, every file headed and every screen built from design tokens. --- ## πŸ—Ί Roadmap - [ ] Multi-model residency (keep 2+ small models warm simultaneously) - [ ] Prompt-cache persistence across launches (MLX `saveCache`) for instant long-context reload - [ ] Vision-language models (MLXVLM) β€” image input for Gemma-3 / Qwen-VL class models - [ ] Tool calling / MCP bridge for local agents - [ ] Speculative decoding with paired draft models - [ ] Sparkle-based in-app updates - [ ] Localization (French first πŸ‡«πŸ‡·) --- ## 🀝 Contributing Issues and pull requests are welcome! 1. Fork, then `git clone` your fork. 2. Follow [Building from source](#%EF%B8%8F-building-from-source) β€” `make build` must pass with **zero warnings**. 3. Match the existing style: design tokens only in views, inference logic only in `Engine/`, mandatory file headers. 4. `ZyquoLocal --verify` should stay green if you touch the engine or Hub layers. 5. Open a PR with a clear description of *what* and *why*. --- ## πŸ“„ License Released under the **[MIT License](LICENSE)** β€” Β© 2026 Simon-Pierre Boucher. --- ## πŸ‘€ Author
**Simon-Pierre Boucher** πŸ“« Contact: [contact@spboucher.ai](mailto:contact@spboucher.ai)
*Zyquo Local is part of the Zyquo family of native macOS AI apps.* ⭐ If Zyquo Local is useful to you, a star helps more people run their AI locally.