Swift on Man-You

Higgins: a neurosymbolic menubar buddy

Mon, 20 Apr 2026 10:00:00 +0200

Higgins is a local assistant that lives in the menubar. A Qwen 2.5 7B model runs on-device via MLX, a SQLite triple store remembers things across sessions, and a small collection of tools — AppleScript runners, EventKit bridges, gh CLI wrappers — lets him actually do work on the Mac. No cloud, no subscription, no data leaving the machine.

The name is a nod to Magnum P.I.’s reserved English major-domo. The vibe was aspirational; most of the engineering effort went into making sure he doesn’t cheerfully hallucinate your dentist appointment into 2023.

Why not just a chat wrapper

The starting pitch was neuro-symbolic: “LLMs are great at vibes and terrible at strict logic; symbolic systems are the opposite; put a logic engine inside a neural one.” Nice in a blog post, vague as a project.

What it actually means in code: the neural side (Qwen) handles language, intent, paraphrasing. The symbolic side (SQLite facts table, typed tool schemas, EventKit queries) handles everything where being wrong is worse than being silent — dates, names, calendar events, PR numbers. The LLM never gets to compute a date from priors; it forwards your words to a parser. The LLM never claims to remember your dog’s name; the fact comes from a SQL row, or it doesn’t answer.

That split is the whole project. Everything else is plumbing.

The Qwen brain

Qwen 2.5 7B Instruct, 4-bit quantized, ~4.5 GB on disk. Loaded via mlx-swift-lm with progress reported through a NSKeyValueObservation on the download’s Progress object — since swift-huggingface fires the handler once then mutates in place, not on every byte.

Picking Qwen over Gemma was almost incidental. Gemma 3 4B worked but wouldn’t accept a system role, forcing a hacky primer-pair trick. Gemma 4 26B-a4b is MoE, which mlx-swift-lm’s Gemma4Model doesn’t implement yet. Qwen accepts system prompts cleanly and, crucially, was trained to emit native tool calls — which matters a lot more than benchmark scores.

The old path was prompt-engineered: TOOL_CALL toolname {...} in the output, parsed with regex. Fragile. Qwen wants to emit something like:

<tool_call>
{"name": "reminder_add", "arguments": {"text": "…", "datetime": "…"}}
</tool_call>

mlx-swift-lm surfaces this as .toolCall(ToolCall) events in the generation stream, if you pass structured tool specs into UserInput(chat:, tools:). Once wired up, the model stops inventing its own format and starts using the one it was RL’d on.

Generation loop excerpt

for await gen in try MLXLMCommon.generate(input: input, parameters: params, context: context) {
 switch gen {
 case .chunk(let s): output += s
 case .toolCall(let c): call = c
 case .info: break
 }
}

The text parser stuck around as a fallback for edge cases.

The symbolic side

A SQLite file at ~/Library/Application Support/Symbolic/memory.db with two tables:

CREATE TABLE episodes(
 id INTEGER PRIMARY KEY,
 user_msg TEXT, assistant_reply TEXT,
 signal INTEGER, ts REAL
);
CREATE TABLE facts(
 id INTEGER PRIMARY KEY,
 subject TEXT, predicate TEXT, object TEXT,
 confidence REAL, last_seen REAL,
 UNIQUE(subject, predicate, object)
);

Episodes are the raw log: every chat turn lands here. Facts are the distilled, queryable form — subject/predicate/object triples with a confidence score. The interesting work happens in the pipe between the two.

Sleep

The consolidation metaphor is cribbed directly from human memory: episodic hippocampal traces don’t become semantic knowledge until you sleep. Higgins does the same. After 15 minutes of chat silence, or when you tap the 🌙 button, he runs a pass:

NREM: the model reads the day’s recent episodes and emits one JSON object per line — extracted stable facts about you, your world, your preferences. Ephemeral conversational filler (greetings, acknowledgments, weather chat) is skipped.
Synaptic downscaling: every fact’s confidence is multiplied by 0.95. Unused memories decay. Recalled ones get re-bumped above 1.0 and capped.
Purge: facts below 0.05 confidence are dropped.
Dream log: a human-readable markdown summary lands in ~/Library/Application Support/Symbolic/dreams/YYYY-MM-DD.md.

Sleeper entrypoint

func nightCycle(episodeLimit: Int = 100) async throws -> Report {
 let episodes = try await store.recentEpisodes(limit: episodeLimit)
 let facts = await extractFacts(from: episodes)
 for f in facts {
 try await store.addFact(subject: f.subject, predicate: f.predicate, object: f.object)
 }
 try await store.decayFacts(multiplier: 0.95)
 let purged = try await store.purgeWeakFacts(threshold: 0.05)
 // ...
}

There’s no remember command to learn. Facts accumulate while you use the thing.

Per-turn recall: closing the loop

Sleep would be useless if the facts just piled up. Before each generation, the user’s query is keyword-matched against the facts table (top 5 hits, LIKE on subject/predicate/object). Matching facts are injected into that turn’s system context as a bracketed prefix:

[Known facts from memory:
- dog / name / Rex (confidence 0.95)
- manz / employer / Woosmap (confidence 0.87)
]
what's my dog's name?

History stays clean — the decoration only exists for the single inference call. No tool call needed for the model to answer “Rex”. The symbolic substrate grounds the neural output on the way past.

At low scale (hundreds of facts) LIKE matching is good enough. Embedding-backed similarity search is the upgrade when it isn’t.

Tools

The tool layer is where the project actually earns its keep. Three surfaces:

AppleScript library. Curated scripts live in ~/Library/Application Support/Symbolic/scripts/, each with frontmatter metadata (-- name:, -- description:, -- args:). Seed scripts ship with the app; the user can edit or add more. The model calls them by name — calendar_today, note_quick, etc. — as if they were first-class tools.

EventKit bridge. AppleScript against Calendar.app is infamously slow — iterating every event on every calendar through the bridge takes 30+ seconds for a busy calendar. EventKit queries the same data in milliseconds. The catch: it needs NSCalendarsFullAccessUsageDescription in a real Info.plist. The SPM executable embeds one via a linker trick:

Package.swift

linkerSettings: [
 .unsafeFlags([
 "-Xlinker", "-sectcreate",
 "-Xlinker", "__TEXT",
 "-Xlinker", "__info_plist",
 "-Xlinker", "Resources/Info.plist",
 ]),
]

-sectcreate __TEXT __info_plist injects the plist into a section TCC reads when deciding whether to prompt for permission. Works without wrapping the binary in a .app bundle.

gh CLI wrappers. gh_my_prs, gh_review_queue, gh_notifications, gh_recent_merged. Subprocess calls to the user’s existing gh session — no OAuth dance, no token storage. A ProcessRunner actor handles timeouts and respects Task.isCancelled so a stuck subprocess doesn’t freeze the UI when you hit the red stop button.

Tool results render as folded cards with a wrench icon, tool name, and a one-line summary. Click to expand. Errors auto-expand. #123 · PR title · owner/repo links are real anchors thanks to MarkdownUI on the assistant-side rendering.

Dates, or: why the model doesn’t do arithmetic

7B models are bad at date math. “Remind me tomorrow at 8:15” reliably produced ISO strings from 2023, 2024, anywhere but actually tomorrow.

The fix is to not let the model do arithmetic at all. Any tool argument named datetime, when, due_date, etc. gets intercepted in Swift before dispatch. A tiny table handles English and French relative words (tomorrow, today, demain, hier) — NSDataDetector isn’t locale-parameterizable and picks up the system locale, which fails on English keywords under a French macOS. Anything the table doesn’t catch falls through to NSDataDetector, which anchors relative phrasing against Date().

Critically, the user’s raw message is the source of truth, not the model’s output. If you typed “tomorrow”, “tomorrow” is what gets parsed — even if the model hallucinates an ISO. The model’s job is intent extraction, not date reasoning.

The AppleScript Run button

When the model writes code in an assistant reply, the code block renders with a language tag and a copy button. When the language is applescript, a Run button appears:

CodeBlock with conditional run action

MarkdownUI.Markdown(turn.text)
 .markdownBlockStyle(\.codeBlock) { config in
 CodeBlock(
 code: config.content,
 language: config.language ?? "",
 onRun: runAction(for: config.language ?? "", code: config.content)
 )
 }

The action shells out to osascript -e <script>, captures stdout, appends the result as a tool turn. The user stays in charge — nothing runs without the click. Safer than giving the model unrestricted automation tools, more flexible than the curated script library.

What grew out of it

The original plan was to fine-tune a custom voice — a “genius caveman” Grug, all short fragments. Hours of LoRA experiments on Gemma 2 2B, Gemma 3 4B, Gemma 4 E4B later, the honest conclusion: voice tuning on small models produces caricature or collapse, and nobody cares about voice when the tools don’t work. The pivot was embracing stock Qwen and pouring the effort into the symbolic substrate instead.

What’s there now:

On-device Qwen 2.5 7B with native tool calling, loading with proper progress feedback
Conversation persistence as JSONL (machine) + Markdown sidecar (human), auto-saved per turn, restored on launch if recent
Tool calls through Qwen’s native format, fallback text parser, per-tool timeouts, cancel button, pending spinner
Sleep/nap consolidation turning episodes into facts, confidence decay, dream logs
Per-turn recall grounding generation on stored facts without touching history
EventKit for calendar/reminders in milliseconds, gh CLI for GitHub, NSDataDetector for natural-language dates
Right-click menu: new conversation, sleep now, open dreams/conversations/memory in Finder
Markdown-rendered assistant replies via MarkdownUI, plain monospaced tool output
AppleScript Run button on any applescript code block in a reply

The fine-tune loop (REM-derived training candidates → periodic LoRA refresh of stable voice and high-confidence facts) is designed but deferred. Retrieval has a faster iteration loop; weights-baking earns its keep when retrieval stops being enough. Given Higgins has had exactly zero users for three days, that threshold is a while off.

Meanwhile he tells me what’s due tomorrow, doesn’t make up dates, remembers the cat’s name is Charlie, and opens PR review queues when I ask. Good enough for now.

The most useless way to port a macOS app

Tue, 24 Mar 2026 09:30:00 +0100

I grew up fascinated by projects like GNUStep, Haiku, Etoile, Wine, and ReactOS. Engineering feats, all of them. They reverse-engineer or reimplement entire operating system APIs so that software written for one platform can run on another. And they almost always end up in the same place: impressive technically, starved for contributors, forever chasing a moving target they can never quite catch.

I never liked the state of the Linux desktop either. Not because it’s bad per se, but because it’s fragmented. A KDE app on GNOME looks alien. Firefox rolls its own everything. GTK and Qt will never agree on anything. Every toolkit draws its own widgets, manages its own text rendering, handles its own accessibility story. The result is a desktop that feels like a coalition of independent projects rather than a coherent system.

This project is not going to fix any of that. But it’s an interesting story about how a combination of prior work, Apple open-sourcing key components, and an AI pair programmer led me down a rabbit hole I didn’t plan to enter.

The prior art that made this possible

I’ve been working with wgpu (Rust’s WebGPU implementation) for a while now, building a map renderer for Woosmap. That project taught me the fundamentals: how to manage GPU pipelines, how to do instanced rendering, how to deal with text atlases and glyph rasterization, how to bridge Rust and Swift through UniFFI.

On the Swift side, I had two apps: Tunes, a music player, and Leela, an internal management tool for Woosmap services. Both are SwiftUI apps, both depend on Apple’s frameworks in the usual way.

So one evening, half-curious and half-joking, I fed Claude the source of those projects alongside some context about GNUStep and friends, and typed:

“What would it take to make Tunes build and run on Linux?”

And then things got out of control.

What Claude came back with

The answer was, predictably, “a lot.” But the interesting part was the breakdown. SwiftUI is the main dependency, and SwiftUI is closed-source. But Swift itself is open-source. Swift Foundation is open-source. The Swift Package Manager works on Linux. So the gap is really:

A SwiftUI implementation (the view hierarchy, state management, layout engine, modifiers)
Some AppKit shims (NSColor, NSAppearance, the bits that SwiftUI still leans on)
A rendering backend that isn’t Core Animation or Metal
A compositor to manage windows, menus, and the desktop chrome

Instead of stopping at “that’s insane, don’t do it,” I kept going. Claude kept going. We started building.

Architecture

The project (codenamed Clone) splits pretty naturally along a language boundary.

Rust does what Rust is good at: GPU work. A wgpu renderer with pipelines for rectangles, rounded rects (SDF-based, because I can’t stop using SDFs apparently), shadows, text via a glyph atlas, and wallpapers. It also runs the window compositor through winit.

Swift does what Swift is good at: UI. A from-scratch SwiftUI implementation (about 50 View types, @State/@Binding/@Environment, ViewBuilder, layout, modifiers), the whole declarative stack. Plus enough AppKit shims to keep real apps happy, a SwiftData reimplementation backed by SQLite, and an IPC protocol over Unix sockets.

UniFFI bridges the two. Each frame, Rust asks Swift for render commands, Swift resolves the view tree into a flat list of positioned primitives, and Rust batches them into instanced GPU draws. It’s the same bridge I use in the map renderer, so at least that part wasn’t new territory.

graph LR
A["App.body"] --> B["ViewBuilder"] --> C["_resolve()"] --> D["Layout"]
D --> E["CommandFlattener"] --> F["IPC
CGFloat → Float"] --> G["Rust batcher"] --> H["wgpu draws"]
style A fill:#c4a7e7,stroke:#6e6a86,color:#191724
style B fill:#c4a7e7,stroke:#6e6a86,color:#191724
style C fill:#c4a7e7,stroke:#6e6a86,color:#191724
style D fill:#c4a7e7,stroke:#6e6a86,color:#191724
style E fill:#f6c177,stroke:#6e6a86,color:#191724
style F fill:#f6c177,stroke:#6e6a86,color:#191724
style G fill:#9ccfd8,stroke:#6e6a86,color:#191724
style H fill:#9ccfd8,stroke:#6e6a86,color:#191724

First signs of life

The moment I’ll remember is the grey rectangle. “Clone Desktop” in the center, a dock at the bottom with colored squares. I’d been at it for hours, wrestling with UniFFI bindings and layout math, and suddenly there it was: pixels on screen, drawn by Swift code, pushed through a Rust GPU backend, on something that was decidedly not macOS.

Day one: a grey box, a label, and a dock. It's not much, but it compiles and renders.

Settings and Finder

Once the basic views worked (stacks, text, lists, navigation), I needed something real to throw at them. Settings was a natural first target: sidebars, forms, toggles, text fields, the kind of layout variety that breaks things fast. Finder came next because browsing a directory with List and ForEach is such a fundamental SwiftUI pattern that if it didn’t work, nothing would.

Settings showing Wi-Fi preferences alongside Finder browsing the home directory. Both are SwiftUI apps running through Clone's stack.

Dark mode just kind of happened. Once I shimmed NSAppearance and implemented the semantic color system (Color.primary, .secondary, the system grays), flipping between light and dark was a toggle. A small thing, but unreasonably satisfying: it made the whole experiment feel like a real desktop for the first time.

The same Settings app in light mode. Appearance switching works through the reimplemented NSAppearance and Color system.

Tunes

This was the whole point, remember? “What would it take to make Tunes build and run on Linux?” Well, it builds. The login sheet renders inside the app window rather than as a separate NSPanel (a compromise, but not a terrible one), and the SwiftUI code is essentially unchanged. TextField, SecureField, Toggle, Button, Link: they all resolve and render. Same source, different universe.

Tunes running its login flow through Clone. The sheet renders in-window rather than as a separate panel, one of many compromises.

Leela

Leela is a management dashboard for Woosmap services: tabs, lists, nested navigation, version selectors, deploy queues. Most of the UI is driven by API responses, so it hammers ForEach with dynamic data, @StateObject, and conditional rendering. If Settings was a stroll through the park, Leela was a stress test.

Leela's services view running through Clone. Tabs, lists, version badges, sidebar navigation, all SwiftUI, all reimplemented.

I won’t pretend it was smooth. Getting here meant implementing a surprising amount of SwiftUI’s surface area. The state management system alone (StateGraph, scoped identity for ForEach, call-index disambiguation) went through several iterations where everything would render once and then silently stop updating. The kind of bug where you stare at a diff for an hour before realizing a closure captured a copy instead of a reference.

Under the hood

Text rendering

Text goes through cosmic-text for shaping, then gets rasterized into a 4096x4096 glyph atlas (single-channel, R8). Each glyph is cached and rendered as an instanced GPU quad. Fonts are bundled: Inter for UI text, Phosphor for icons.

This is almost certainly not how Apple does it. A real system would share GPU textures between the compositor and app, or pull from a system font cache. But it works, and there’s a special joy in watching a glyph atlas fill up character by character as the UI renders for the first time.

Layout

I reverse-engineered SwiftUI’s layout by reading objc.io’s thinking-in-swiftui and a lot of trial and error. The model: parents propose a size to children, children report back what they need, parents position them. Sounds simple until ZStack enters the picture: nil-sized views from .background() modifiers would expand to fill constraints and eat space from real siblings. That one took a while.

ScrollView was another head-scratcher: it fills its proposed size but lays out content unbounded in the scroll axis. Getting that inversion right, where the container constrains in one direction and is infinite in the other, broke my mental model twice before clicking.

IPC

Each app is a separate process. The compositor (CloneDesktop) runs the Rust event loop and manages surfaces. Apps connect over a Unix socket at /tmp/clone-compositor.sock and exchange length-prefixed JSON messages. There’s an annoying CGFloat-to-Float conversion at the wire boundary: Swift thinks in 64-bit coordinates, the GPU thinks in f32, and someone has to reconcile that at the border.

The `ycodebuild` trick

This is probably my favorite hack in the project. To compile an existing macOS app against Clone instead of Apple’s frameworks, ycodebuild generates a shadow SPM package that maps import SwiftUI to Clone’s SwiftUI, import AppKit to Clone’s shims, and so on. The app source code doesn’t change at all: you just build against a different package graph, and the compiled binary talks to the compositor over the socket. The same .swift file, two completely different platforms.

Honest assessment

I should be upfront about the gap between “it renders” and “it works.”

Animations are mostly stubbed. Accessibility is nonexistent. The compositor redraws every surface every frame like it’s 1997. There are // TODO: implement scattered across the codebase where AppKit APIs return no-ops and hope nobody notices. Sheets render in-window because I never built the panel system. The glyph atlas will fall over the moment someone opens a CJK document.

And (this is the awkward part) it doesn’t actually run on Linux yet. The whole premise was “what would it take,” and the answer turned out to include some Apple framework dependencies I haven’t replaced with their open-source equivalents. It’s doable. It’s just not done.

But here’s the thing that caught me off guard. The time from that initial Claude prompt to a state where Tunes and Leela compile and render recognizable UI was hours, not weeks. Not autonomous AI magic (plenty of manual fixes and architectural decisions along the way) but Claude carried an enormous amount of boilerplate: generating 50 View type stubs, wiring up modifier chains, implementing the state graph, setting up IPC. The kind of work that would’ve taken me days of tedious typing, compressed into a conversation.

Why this matters (a little)

Apple open-sourcing Swift and Foundation was a bigger deal than most people realize. Not because anyone’s going to ship a SwiftUI app on Linux tomorrow, but because it lowered the floor for experiments like this from “completely impossible” to “merely impractical.”

The projects I admired growing up (GNUStep, Haiku, Wine) were built by small teams reverse-engineering closed systems over years. The combination of open-source language infrastructure and AI assistance compresses that timeline dramatically. Not to a point where it’s practical or production-ready, but to a point where a single person can explore the shape of the problem in a weekend.

That’s the real takeaway. Not “I ported macOS to Linux.” I didn’t. But I went from a throwaway prompt to colored boxes on screen running real SwiftUI app code, and that felt like something worth writing about.

What’s next

Honestly? Probably nothing. The project scratched a twenty-year itch. But I know myself, and I know there’s a Kawase blur pipeline sitting unused in the renderer that’s going to call my name at 11pm some Tuesday. If I do keep going:

Per-window offscreen textures: the compositor shouldn’t redraw everything every frame, that’s embarrassing
Glassmorphism / backdrop blur: because what’s the point of reimplementing macOS if you can’t have the frosted glass
Actually running on Linux: the whole original premise, still unfinished
Shared GPU textures: how a real compositor would work, instead of copying pixels through a socket like an animal

Or maybe it stays as a weekend experiment and a blog post. Either way, the kid who thought GNUStep was the coolest thing ever is pretty happy right now.

Tunes

Tue, 01 Jul 2025 10:31:38 +0200

iTunes Match worked great for years: you uploaded your library, Apple matched what it could, and you had access to everything from any device. But Apple is clearly moving everyone toward Apple Music, and iTunes Match has been slowly rotting. The writing was on the wall.

I didn’t want to subscribe to Apple Music. I wanted to keep my library, my ratings, my play counts, my playlists, all the metadata accumulated over 20 years. So I built my own streaming setup: a Go backend that serves the library over HTTP, and SwiftUI apps that play it on iOS, macOS, and tvOS.

Exporting the library

Apple Music (formerly iTunes) can export the library as an XML plist file. It’s a flat dictionary of tracks keyed by ID, with every field you’d expect: name, artist, album, play count, rating, date added, file location, and about 60 more.

A track entry in the exported XML

<key>1234</key>
<dict>
 <key>Track ID</key><integer>1234</integer>
 <key>Name</key><string>Windowlicker</string>
 <key>Artist</key><string>Aphex Twin</string>
 <key>Album</key><string>Windowlicker</string>
 <key>Total Time</key><integer>381573</integer>
 <key>Location</key><string>file:///Music/Aphex%20Twin/Windowlicker/01%20Windowlicker.m4a</string>
</dict>

The Go struct that maps to this uses plist tags for XML parsing and gorm tags for database storage, with every optional field as a pointer for proper nil handling:

Track model (abbreviated)

type ITunesTrack struct {
 TrackID *int `plist:"Track ID" json:"track_id" gorm:"primaryKey"`
 Name *string `plist:"Name" json:"name" gorm:"index"`
 Artist *string `plist:"Artist" json:"artist" gorm:"index"`
 Album *string `plist:"Album" json:"album" gorm:"index"`
 TotalTime *int `plist:"Total Time" json:"total_time"`
 Location *string `plist:"Location" json:"location"`
 Rating *int `plist:"Rating" json:"rating" gorm:"index"`
 PlayCount *int `plist:"Play Count" json:"play_count"`
 DateAdded *time.Time `plist:"Date Added" json:"date_added" gorm:"index"`
 // ... 60+ more fields
}

The initial version parsed the XML on every startup using howett.net/plist. That worked fine for a 15,000-track library (about 2 seconds of parsing). But it eventually moved to SQLite with GORM for persistence, which also enabled FTS5 full-text search and pre-aggregated album caches.

The Go backend

The server is straightforward. A LibraryService holds the database, artwork cache, rate limiter, and various sub-services. Routes are plain net/http handlers with a JWT auth middleware:

Route setup (abbreviated)

// Auth routes (no middleware)
http.HandleFunc("/auth/login", authHandlers.HandleLogin)
http.HandleFunc("/auth/register", authHandlers.HandleRegister)

// Library routes (auth required)
http.Handle("/tracks", authMiddleware(http.HandlerFunc(service.HandleTracks)))
http.Handle("/artists", authMiddleware(http.HandlerFunc(service.HandleArtists)))
http.Handle("/albums", authMiddleware(http.HandlerFunc(service.HandleAlbums)))
http.Handle("/stream/", authMiddleware(http.HandlerFunc(service.HandleStream)))
http.Handle("/artwork/track/", authMiddleware(http.HandlerFunc(service.HandleTrackArtwork)))

The /stream/{id} endpoint serves audio files directly with http.ServeFile, which handles range requests and conditional caching automatically. No need to build a custom streaming protocol. HTTP does the job.

Authentication uses Argon2 for password hashing and session tokens stored in the database. It later grew WebAuthn support for passkey login, and a QR code flow for tvOS (where typing passwords with a remote is painful).

Album artwork

This was the most annoying part. The exported XML doesn’t include artwork. The actual cover images are either embedded in the audio files or live somewhere in Apple’s ecosystem that isn’t accessible after export.

The solution is a three-tier artwork system:

Embedded extraction: read the audio file metadata with github.com/dhowden/tag, pull out the cover image if present, cache it locally
iTunes Store lookup: search Apple’s public API for the album, download the highest resolution artwork available
Manual upload: for albums that don’t match either source

The iTunes Store lookup uses a scoring system to match results. Exact album + artist name match scores highest, partial matches score lower, and anything below a minimum threshold is rejected:

iTunes Store artwork search

func (ls *LibraryService) searchITunesStore(artist, album string, tracks []ITunesTrack) *ITunesSearchItem {
 searchTerm := fmt.Sprintf("%s %s", strings.TrimSpace(artist), strings.TrimSpace(album))

 params := url.Values{}
 params.Set("term", searchTerm)
 params.Set("entity", "album")
 params.Set("media", "music")
 params.Set("limit", "10")

 searchURL := fmt.Sprintf("https://itunes.apple.com/search?%s", params.Encode())
 // ... fetch, decode, find best match by score
}

Apple’s API returns 100x100 thumbnails by default. The URL pattern is predictable (replace 100x100 with 600x600), but not all resolutions exist for all albums. The server tries 600, 512, and 300 with HEAD requests before falling back to the original.

The real constraint is rate limiting. Apple’s Search API starts returning 403s if you hit it too hard. The server uses a channel-based rate limiter that caps requests to 2 per second by default, configurable via TOML config.

The gapless playback problem

This one took a while to figure out. Live albums, DJ mixes, classical recordings: any music that’s supposed to flow continuously between tracks gets a gap when played back on iOS.

The root cause: iOS AVFoundation ignores the iTunSMPB gapless metadata in MP3 files. This is the atom that tells the player how many encoder delay and padding samples to skip. Apple’s own Music app reads it. AVFoundation does not.

The fix is converting MP3s to AAC. The AAC container stores gapless information in a way that AVFoundation actually respects. The server has a built-in transcoder:

Startup conversion

transcoder := tunes.NewTranscoderService(service, tunes.TranscodeOptions{
 Concurrency: 4,
 DeleteSource: false, // Keep original MP3s
})
results, err := transcoder.ConvertAllMP3s(context.Background())

It uses ffmpeg under the hood, runs 4 workers in parallel, keeps the originals, and updates the database paths. A 15,000-track library takes a couple of hours. After that, gapless playback works perfectly.

SwiftUI clients

The app targets iOS, macOS, and tvOS from a single codebase, with platform-specific extensions for navigation and layout. iOS uses tab navigation with a mini-player overlay, macOS uses a split view with sidebar, and tvOS uses focus-based navigation for the remote.

The audio player is built on AVQueuePlayer for seamless track transitions. It pre-buffers the next track 10 seconds before the current one ends, maintaining up to 3 items in the queue at any time.

One hard-won lesson: @Published property updates in background cause iOS to terminate the app for excessive main-thread UI work. The fix is gating all published writes behind a foreground check:

Background-safe state management

struct PlaybackState: Equatable {
 var currentTime: TimeInterval = 0
 var duration: TimeInterval = 0
 var isPlaying = false
 var isLoading = false

 static func == (lhs: PlaybackState, rhs: PlaybackState) -> Bool {
 return Int(lhs.currentTime) == Int(rhs.currentTime) &&
 Int(lhs.duration) == Int(rhs.duration) &&
 lhs.isPlaying == rhs.isPlaying &&
 lhs.isLoading == rhs.isLoading
 }
}

Grouping related properties into structs (instead of individual @Published vars) and implementing coarse equality comparison reduced SwiftUI re-renders significantly. The player only triggers a view update when the second changes, not on every time observer tick.

The API layer uses Combine publishers with automatic 401 retry: if a request fails with an expired token, the service transparently refreshes it and replays the original request. Network monitoring via NWPathMonitor lets the app degrade gracefully when offline, falling back to Core Data for cached data.

What grew out of it

What started as “stream my library from a Raspberry Pi” has accumulated features over time:

Full-text search with SQLite FTS5 across all track metadata
Play history tracking: every play gets logged with duration and completion status, which feeds a yearly replay feature (like Spotify Wrapped)
Lyrics: embedded USLT frames from audio files, plus LRClib API integration for synced timestamps
Offline mode: Core Data persistence with background sync, download management for keeping albums locally
Discogs integration: artist biographies and metadata from a separate database
Vector similarity search: track embeddings for “genius playlists” based on audio features and metadata

It’s not a replacement for Apple Music. It doesn’t have a catalog of 100 million songs. But it plays my music, with my metadata, on all my devices, without a subscription. That was the goal.

Swift on Man-You

Higgins: a neurosymbolic menubar buddy

Why not just a chat wrapper

The Qwen brain

The symbolic side

Sleep

Per-turn recall: closing the loop

Tools

Dates, or: why the model doesn’t do arithmetic

The AppleScript Run button

What grew out of it

The most useless way to port a macOS app

The prior art that made this possible

What Claude came back with

Architecture

First signs of life

Settings and Finder

Tunes

Leela

Under the hood

Text rendering

Layout

IPC

The ycodebuild trick

Honest assessment

Why this matters (a little)

What’s next

Tunes

Exporting the library

The Go backend

Album artwork

The gapless playback problem

SwiftUI clients

What grew out of it

The `ycodebuild` trick