spb/zyquo-cloud Public MIT
Native macOS AI chat client for 12 cloud providers — your keys, every cloud model, one beautiful chat.
Swift 97.4%
Shell 1.7%
Makefile 1%
1<!--2 README.md3 Zyquo Cloud4 Author: Simon-Pierre Boucher5 Mail: contact@spboucher.ai6-->78<div align="center">910<img src="assets/readme/icon.png" width="180" alt="Zyquo Cloud icon" />1112# ☁️ Zyquo Cloud1314### *Your keys, every cloud model, one beautiful chat.*1516**A truly native macOS AI chat client for 12 cloud providers — built entirely without Xcode.**1718<br/>1920[](https://github.com/spboucher-ai/zyquo-cloud/releases/latest)21[](https://github.com/spboucher-ai/zyquo-cloud/releases/latest)22[](https://swift.org)23[](LICENSE)2425[](https://github.com/spboucher-ai/zyquo-cloud/releases)26[](#-installation)27[](#-supported-providers)28[](#-live-api-verification)2930<br/>3132<img src="assets/readme/screenshot-chat.png" width="850" alt="Zyquo Cloud — chat with syntax-highlighted code and markdown tables" />3334</div>3536---3738## 📖 Table of Contents3940- [✨ Features](#-features)41- [🔌 Supported Providers](#-supported-providers)42- [🖼 Screenshots](#-screenshots)43- [📦 Installation](#-installation)44- [🧰 Requirements](#-requirements)45- [🚀 Usage](#-usage)46- [🔐 Security & Privacy](#-security--privacy)47- [🧪 Live API Verification](#-live-api-verification)48- [🛠 Building from Source](#-building-from-source)49- [🏛 Architecture](#-architecture)50- [🗺 Roadmap](#-roadmap)51- [🤝 Contributing](#-contributing)52- [📄 License](#-license)53- [👤 Author](#-author)5455---5657## ✨ Features5859Every feature below exists in the shipped code — nothing aspirational.6061### 💬 Core chat6263- **True token-by-token streaming** over Server-Sent Events, with a stop button (`⌘.`), a blinking64 stream caret, smooth auto-scroll and a *"Jump to latest"* pill when you scroll up.65- **Switch model per conversation *and* per message** — start a thread on GPT, get a second opinion66 from Claude, regenerate with DeepSeek. The model chip in the header opens a searchable picker67 grouped by provider, with favorites (⭐) pinned first and capability badges (👁 vision, 🧠 reasoning,68 🔧 tools) plus context-window and pricing info on every row.69- **Reasoning / extended-thinking display**: models that think (DeepSeek V4, Qwen thinking models,70 Claude extended thinking, Kimi K-series, Mistral Magistral-style chunks…) stream their thought71 process into a collapsible *"Thinking…"* section, kept separate from the answer.72- **Perplexity citations** rendered as numbered, clickable source chips under the answer.73- **Message actions** on hover or right-click: copy, **edit & resend** (rewinds the thread), 74 **regenerate**, quote-reply, delete.75- **Token usage & estimated cost** per message (hover) and per conversation (info popover +76 sidebar footer), computed from each model's real pricing.77- **Per-conversation system prompt** + a global default; **generation parameters**78 (temperature, top-p, max tokens, penalties, reasoning effort, thinking toggle) — the editor only79 shows the parameters the selected model actually supports.8081### 🖼 Vision & attachments8283- **Drag & drop or attach images** (PNG/JPEG/WebP/GIF) for vision-capable models — encoded to each84 provider's format automatically (OpenAI `image_url` data-URIs, Anthropic base64 content blocks).85- **Drop text/code files** (30+ extensions) — contents are injected inline, fenced with the filename.86- 56pt thumbnails above the input with one-click removal; dashed accent highlight while dragging.8788### ⚡ Productivity8990- **Prompt Library** — 58 hand-crafted built-in templates across 8 categories (Writing, Coding,91 Analysis, Translation, Business, Learning, Creativity, Productivity), each with a `{{input}}`92 slot, plus your own custom templates.93- **Personas** — 8 thoughtful built-ins (Senior Code Reviewer, Socratic Tutor, Ruthless Editor…)94 bundling a system prompt + preferences; apply one from the palette in two keystrokes.95- **⌘K Command Palette** — one search box over models, templates, and personas.96- **Quick Chat (⌥Space)** — a global, Spotlight-style floating panel available from any app:97 ask, read the streamed answer, then *"Continue in Zyquo Cloud"* to promote it to a full thread.98- **Compare mode** — broadcast one prompt to **2–4 models side-by-side**, each column streaming99 independently with its own copy/regenerate.100- **Export** any conversation to **Markdown** or **PDF** (thinking sections and citations included).101- **Full-text search** across all conversations (titles *and* message bodies), plus pin, rename,102 tags, and automatic *Pinned / Today / Yesterday / Previous 7 Days / Older* grouping.103- **Automatic titles** — after the first exchange, the cheapest non-reasoning model of the same104 provider names the conversation.105106### 🧠 Model management107108- **170 built-in chat models**, every one verified live against the real APIs (see109 [verification](#-live-api-verification)).110- **Dynamic refresh** — pull `/models` from any provider and diff it against the catalog.111- **Custom models & endpoints** — add any OpenAI-compatible endpoint (OpenRouter, Groq, self-hosted112 gateways…) with a custom model ID and base URL.113114### 🍎 macOS-native polish115116- 100 % **SwiftUI + AppKit**, no Electron, no web views — launches instantly.117- **Menu bar extra** (toggleable) with a template glyph that adapts to light/dark menu bars.118- **Light & dark themes** from one semantic token system (sky-indigo accent + 4 alternates),119 adjustable chat font size (12–18 pt) with live preview.120- Full keyboard: `⌘N` new chat · `⌘K` palette · `⌘F` search · `⌘↩` send · `⌘⇧E` export ·121 `⌥Space` Quick Chat · `⌘.` stop.122- **Markdown done right**: headings, nested lists, task lists, blockquotes, GFM tables with123 alternating row tints, links — and code blocks with a language label, hover copy button, and a124 built-in syntax highlighter covering **11 language families** (Swift, Python, JS/TS, JSON,125 HTML/CSS, Bash, SQL, Go, Rust, C/C++/Obj-C).126127---128129## 🔌 Supported Providers130131| Provider | Wire format | Dynamic `/models` | Notable support |132|---|---|:---:|---|133| **OpenAI** | OpenAI | ✅ | GPT-5.x families, o-series reasoning, vision |134| **Anthropic** | Native Messages API | ✅ | Claude 5 / 4.x, extended thinking, vision blocks |135| **xAI** | OpenAI-compatible | ✅ | Grok 4.5 / 4.3 / 4.20, reasoning effort |136| **Mistral** | OpenAI-compatible | ✅ | Large/Medium/Small, Codestral, reasoning chunks |137| **Google Gemini** | OpenAI-compat endpoint | ✅ | Gemini 3.x / 2.5, thought signatures tolerated |138| **Alibaba Qwen** (DashScope intl) | OpenAI-compatible | ✅ | Qwen 3.x families, `enable_thinking`, QwQ/QVQ |139| **DeepSeek** | OpenAI-compatible | ✅ | V4 Flash/Pro, `reasoning_content` streaming |140| **Kimi** (Moonshot) | OpenAI-compatible | ✅ | K3 / K2.x, moonshot-v1 vision |141| **Perplexity** | OpenAI-compat + search | — | Sonar family, citations & search results |142| **Together AI** | OpenAI-compatible | ✅ | Curated serverless catalog (Llama, DeepSeek, Qwen…) |143| **DeepInfra** | OpenAI-compatible | ✅ | Open models + proxied Claude/Gemini |144| **Cerebras** | OpenAI-compatible | ✅ | Ultra-fast inference, `max_completion_tokens` |145146Provider quirks (auth headers, `stream_options`, `reasoning_effort` value sets, streaming-only147models, completions-style deltas, keep-alive comments…) are all isolated in the provider layer —148documented in [`docs/PROVIDERS.md`](docs/PROVIDERS.md), a 1,600-line API research dossier.149150---151152## 🖼 Screenshots153154<div align="center">155156**Chat — syntax-highlighted code, GFM tables, per-message cost**157158<img src="assets/readme/screenshot-chat.png" width="850" alt="Chat view" />159160<br/><br/>161162**Empty state — model chip and suggested prompts**163164<img src="assets/readme/screenshot-empty.png" width="850" alt="Empty state" />165166</div>167168---169170## 📦 Installation171172### Download (recommended)1731741. Grab **[`ZyquoCloud.dmg` from the latest release](https://github.com/spboucher-ai/zyquo-cloud/releases/latest)**.1752. Open the DMG and drag **Zyquo Cloud** into **Applications**.1763. Launch it. No Gatekeeper warnings: the app is **Developer ID-signed, notarized by Apple, and177 stapled** (`spctl` verdict: *accepted — Notarized Developer ID*), universal **arm64 + x86_64**.178179### First run180181Open **Settings → Providers & Keys** (`⌘,`), paste the API keys for the providers you use, and hit182**Test** — a green dot and the round-trip latency confirm each key. That's it.183184---185186## 🧰 Requirements187188| | |189|---|---|190| **macOS** | 13 Ventura or later |191| **Architecture** | Apple Silicon & Intel (universal binary) |192| **Accounts** | Your own API keys for the providers you want (BYOK — no subscription, no middleman) |193| **Network** | Outbound HTTPS to the providers you configure — nothing else |194195---196197## 🚀 Usage198199| Action | How |200|---|---|201| New chat | `⌘N` or the sidebar button |202| Send | `⌘↩` |203| Stop generating | `⌘.` or the stop button |204| Switch model | Click the model chip, or `⌘K` |205| Insert a prompt template / apply a persona | `⌘K` |206| Quick Chat from anywhere | `⌥Space` |207| Compare 2–4 models | Split icon in the chat header |208| Search conversations | `⌘F` |209| Export Markdown / PDF | `⌘⇧E` |210| Attach images / files | 📎, drag & drop, or paste |211| Per-conversation parameters | Sliders icon in the input bar |212| System prompt & usage stats | ⓘ in the chat header |213214---215216## 🔐 Security & Privacy217218- **Your keys never leave your Mac.** They live in a single encrypted vault file219 (`~/Library/Application Support/ZyquoCloud/vault.zq`) — **AES-256-GCM** via CryptoKit.220- The master key is derived with **HKDF-SHA256** from a random salt **+ this Mac's hardware UUID +221 your account** + an obfuscated compiled-in pepper: the vault is **machine-bound** and useless if222 copied to another computer. Tampering is detected by the GCM tag.223- **Deliberately no macOS Keychain** — no keychain prompts, no iCloud sync of secrets, fully224 auditable storage. Keys are decrypted only at request time, never logged, and always displayed225 redacted (`••••` + last 4).226- **No telemetry, no analytics, no accounts.** The app talks exclusively to the AI providers you227 configure. Conversations are plain JSON on your disk, exportable and greppable.228- Hardened-runtime binary with an empty entitlement surface (no JIT, no sandbox exceptions).229230---231232## 🧪 Live API Verification233234Zyquo Cloud ships with `zyquo-verify`, a harness that drives the **exact production provider235clients** against the real APIs:236237- lists `/models` on every provider and diffs against the built-in catalog,238- sends a completion to **every one of the 170 catalog models**,239- tests **streaming** on every provider and **vision** on every vision-capable provider.240241Final run: **202 / 202 tests green** across all 12 providers — full table in242[`docs/VERIFICATION.md`](docs/VERIFICATION.md). Run it yourself:243244```sh245cp .env.keys.example .env.keys # add your keys (file is gitignored)246make verify247```248249---250251## 🛠 Building from Source252253No Xcode required — the whole app builds with Swift Package Manager and Command Line Tools.254255```sh256git clone https://github.com/spboucher-ai/zyquo-cloud.git257cd zyquo-cloud258259make # release build → dist/Zyquo Cloud.app (ad-hoc signed)260make run # build + launch261make test # unit test suite (Swift Testing)262make icon # regenerate AppIcon.icns from the SVG sources in assets/icon/263make release # universal binary + Developer ID signing + notarization + DMG264```265266**Toolchain notes** (from real-world CLT-only builds, encoded in the Makefile):267268- Builds pin `SDKROOT` to the macOS 26 SDK — newer SDKs declare SwiftUI property wrappers as269 macros whose compiler plugin only ships with Xcode.270- The x86_64 slice links with `-U __swift_FORCE_LOAD_$_swiftCompatibility56` because CLT ships271 that back-deployment library arm64-only.272- `scripts/test.sh` wires CLT's Swift Testing framework and macro plugin so `make test` works273 without Xcode.274275**Dependencies:** exactly one — [`swift-markdown`](https://github.com/swiftlang/swift-markdown)276(Apple) for Markdown parsing. Networking is plain `URLSession`; crypto is CryptoKit.277278---279280## 🏛 Architecture281282```283Sources/ZyquoCloud/284├── App/ @main entry (GUI + --verify + --load-vault modes), scenes, commands285├── DesignSystem/ ZyquoTheme tokens (colors/type/spacing/radii/motion), components, brand glyph286├── Models/ Conversation, Message, AIModel, ProviderID, Persona, ChatParameters…287├── Providers/ ProviderProtocol · OpenAICompatibleClient (11 providers + custom)288│ · AnthropicClient (native Messages API) · ProviderRegistry289├── Services/ StreamingService (SSE) · ModelCatalog (+ generated data) · SecureKeyStore290│ · PersistenceService · ConversationExporter · prompt/persona libraries291├── ViewModels/ ConversationStore (chat engine) · KeyVaultStore292├── Views/ Chat, Sidebar, Markdown renderer + highlighter, Settings, QuickChat, Compare293└── Verify/ zyquo-verify harness (202-test live sweep)294```295296Design principles: single source of truth everywhere (models only from `ModelCatalog`, colors only297from `ZyquoTheme`), provider quirks never leak past the client layer, structured concurrency298(`async/await` + `AsyncThrowingStream`) with `@MainActor` UI state, zero third-party HTTP/crypto.299300---301302## 🗺 Roadmap303304- [ ] Function calling / tools UI305- [ ] Web search toggle for providers that support it natively306- [ ] Conversation folders with drag & drop307- [ ] Prompt-template variables beyond `{{input}}`308- [ ] Localization (the string layer is centralization-ready)309- [ ] Sparkle-based auto-updates310311Suggestions welcome — open an issue!312313---314315## 🤝 Contributing3163171. Fork, then `git clone` your fork.3182. `make test` must stay green; `make` must build with **zero warnings**.3193. Follow the conventions in [`CLAUDE.md`](CLAUDE.md): design tokens only (no raw hex in views),320 one term per concept, provider quirks stay in the provider layer, and every code file carries321 the standard header.3224. Open a PR with a clear description. For provider/catalog changes, update323 [`docs/PROVIDERS.md`](docs/PROVIDERS.md) and `ModelCatalogData.swift` **together** and include324 a `make verify` run for the affected provider.325326---327328## 📄 License329330Released under the [MIT License](LICENSE) — © 2026 Simon-Pierre Boucher.331332---333334## 👤 Author335336<div align="center">337338**Simon-Pierre Boucher**339340📧 Contact: [contact@spboucher.ai](mailto:contact@spboucher.ai)341342<sub>Part of the <b>Zyquo</b> family of native macOS AI apps.</sub>343344<br/>345346<img src="assets/readme/icon.png" width="48" alt="" />347348</div>349