DEV Community: Sergio Farfan Cardenete

Apple Music Consolidator: merge and dedupe hundreds of Apple Music playlists, safely

Sergio Farfan Cardenete — Wed, 12 Aug 2026 19:32:57 +0000

You switched streaming services. Spotify to Apple Music, or YouTube Music, or Tidal — or you just got tired of paying two subscriptions at once. You ran one of the transfer tools, it churned for twenty minutes, and your playlists appeared in Music. Job done.

Then you started noticing things.

The transfer ran twice, because the first attempt looked like it stalled. Or it ran once, but iCloud Music Library pushed it to your Mac while your old local library was still sitting there. Or you imported from two services that shared half their playlists. Now you have Road Trip, Road Trip, and Road Trip — that last one with a trailing space, which Music is perfectly happy to let you keep — and all three have slightly different contents, because for the last eight months you've been adding songs to whichever one you happened to tap.

Inside them it's worse. The same song sits in one playlist three times: once as your ALAC rip from a CD, once as the 256 kbps Apple Music version, and once as a cloud entry that's now greyed out because the label pulled it. Same title, same artist, same duration. Three rows.

That's how mine got to just under 400 playlists, with dozens of duplicate groups buried in there.

Now try fixing that by hand

Take one triple. Open two of the three side by side, sort both by name, and eyeball 300 rows against another 300 rows. Every time you hit a duplicate, decide which copy to keep — which means checking the bit rate of each one, and noticing that a third one is greyed out. Drag the survivors into a new playlist. Delete the two originals. Hope you didn't miss anything.

Thirty minutes for one group, if you're focused, and nobody stays focused past row 180. Now do that sixty times. That's a weekend gone, and the mistakes are silent: you don't discover you dropped a song until it isn't there on a drive six months later.

And the delete is forever. Music.app has no undo for a deleted playlist, no transaction log, no Recently Deleted. One misclick on a playlist you spent a decade building and it's simply gone.

"Isn't there a tool for this?"

Sort of. I looked before writing anything. Soundiiz is the best-known playlist manager, and it genuinely does have both Merge and Delete Duplicates, and they work with Apple Music. Two things sent me back to my editor:

They're subscription features. Both sit behind Premium — $39/year or $5/month (pricing). The free plan is one-playlist-at-a-time transfers, up to 200 tracks. This is a chore I need to do properly once, and then again the next time a sync goes sideways; a recurring bill for that is a strange trade.

It's a cloud service reaching in through the streaming API. You authorize it against your Apple Music account, and it sees your library the way the API exposes it — as catalog tracks. It cannot see that this copy is your 1,411 kbps ALAC rip, that one is a 256 kbps AAC stream, and the third is flagged "no longer available." That is exactly the information that should decide which duplicate survives. It also can't see the local files that never came from the catalog at all.

Neither approach gives you the thing I actually wanted most: a chance to read the exact change before it happens, and proof afterward that what landed in the library is what I approved — on an operation that has no undo.

So I built Apple Music Consolidator — a native macOS app that merges duplicate playlists and deduplicates the tracks inside them, entirely on your Mac. Nothing is uploaded, no account is connected, nothing is behind a paywall. Every write is planned first, executed through a guarded writer, and then proven correct by reading the library back.

Download the latest .dmg → — open it and drag the app to Applications.

What It Does

Merge — combines playlists into one new <Name> — Merged playlist, deduplicating across copies. Merge same-name copies as a unit, or check off any arbitrary mix of playlists and merge those; the new playlist's description records when it was merged and from which sources. Source playlists are never touched.
Consolidate — deduplicates tracks within one playlist into a new <Name> — Consolidated playlist, with every omitted track individually accounted for.
Batch runs — select any number of playlists and process them unattended. Each one still gets its own fresh library read, its own plan, and its own verification.
Cleanup — delete or rename any playlist behind a single confirmation, or batch-rename a whole page of them with a find/replace fill helper (e.g. strip " — Merged" from thirty playlists in one pass).

How It Works

Everything runs on your Mac, inside one small native app (Swift 6, SwiftUI). It talks to Music.app directly; macOS asks you once for permission to allow that, and the grant survives updates.

What counts as a duplicate. Two tracks match only when their normalized title, normalized artist, and exact duration all agree. Normalization is forgiving where it's safe — curly quotes match straight quotes, dashes match hyphens, extra whitespace and letter case don't matter — and strict where it isn't: accents are preserved, so "Nina" and "Niña" stay different artists, and there is no fuzzy "close enough" matching. A false match silently drops a song you wanted to keep, so when in doubt the app keeps both rows.

Which copy survives. When several tracks match, the app keeps the best one by a fixed, predictable preference: available beats greyed-out, lossless beats lossy, then higher sample rate, then higher bit rate. This is the comparison a cloud service can't make — it takes actually seeing your files. The same library always produces the same answer.

Every change is planned, then proven. No operation ever mutates the library from live state. First the app re-reads your library fresh, then it writes the exact intended change to a small report you can read — every track, every keep-or-omit decision, and why. Only after that does it execute, through a writer that re-checks the playlists one final time immediately before the single create step, and refuses to touch anything that has changed since the plan — or to reuse a playlist that already exists. Then it reads the library back and confirms, track for track, that what landed is what the plan said. If any step disagrees, the app stops and tells you exactly what state it left behind. It never retries and never "repairs" — recovery is always a fresh pass that you start.

Sources are never modified. Merge and Consolidate always create a new playlist. Your originals sit untouched until you delete them yourself in Cleanup, after you've verified the result.

And it's fast. Reading a library through Apple events is normally the slow part of any Music automation. The app fetches data in bulk columns instead of track by track, so scanning ~400 playlists takes about a second, and snapshotting a big playlist takes seconds instead of minutes.

Take It for a Test Drive

Install — download the .dmg, drag the app to Applications, right-click → Open on first launch (it's signed with a personal certificate, not notarized), and grant it permission to control Music.
Scan — one click reads your whole library. Same-name duplicate groups are highlighted automatically.
Pick your victims — in the Merge tab, every playlist is one checklist. Run a duplicate group as a unit, or check any combination and Merge selected as one…
Read the plan — before anything happens, you see exactly what will be created and every duplicate decision the app intends to make.
Apply — a new <Name> — Merged playlist appears, its description recording when it was merged and from which sources. The app reads the library back and confirms the result matches the plan.
Tidy up — happy with the merge? Use Cleanup to batch-delete the originals, or batch-rename to drop the " — Merged" suffix.

Start small: pick one duplicate pair you know well, merge it, and inspect the result in Music before turning it loose on sixty groups. That's what the plan-first design is for.

Build & Install

Easiest: grab AppleMusicConsolidator-<version>.dmg from the latest release (SHA-256 checksum alongside it), open it, and drag the app to Applications.

From source — Swift Package Manager, no Xcode project:

git clone git@github.com:sergio-farfan/MusicConsolidator.git
cd MusicConsolidator/macos-app/ConsolidatorKit
swift test            # 917 tests, fully offline

cd ../..
bash macos-app/scripts/build-app.sh     # build, assemble, sign the bundle
bash macos-app/scripts/package-dmg.sh   # package the installer

Requirements: macOS 14+, Swift 6, and Music.app with an Apple Music library.

Source Code

MIT licensed, on GitHub: github.com/sergio-farfan/MusicConsolidator.

If you're curious about the engineering underneath — the Apple events cost model that took library scans from minutes to seconds, a bug that only reproduced on empty playlists in a live library, and why verification compares strings code point by code point — the full developer notes are in the repo.

Issues and feedback are open — if this untangles your library, I'd love to hear about it.

Built with Swift 6 and SwiftUI on macOS.

RepoDeck: a native macOS dashboard for all your git repos

Sergio Farfan Cardenete — Thu, 09 Jul 2026 05:11:59 +0000

I have somewhere around thirty git repositories checked out on my Mac at any given time — side projects, forks, work I forgot to push before closing the laptop. Every few days I'd ask myself the same question: which of these have uncommitted changes? Which ones are behind their remote and need a pull? The honest answer was always "I don't know," because finding out meant opening each folder in an editor just to glance at the Source Control panel — one repo at a time, over and over.

So I built RepoDeck — a native macOS dashboard that tracks a set of folders, recursively finds every git repository underneath them, and shows you at a glance which ones need attention.

Updated July 2026: five releases have shipped since this was written. The feature list below is current, and Five Releases Later at the end covers what changed — per-repo auto-fetch, repo groups, a ⌘K palette, a diff view with hunk staging, an in-window command runner, and more.

Want to try it right now? Download RepoDeck.dmg → — open it and drag RepoDeck to Applications.

Features

Multi-repo dashboard — track any set of folders; RepoDeck recursively discovers every git repo underneath them
Live status via FSEvents — no polling, no timers; the sidebar badge updates the moment a file changes on disk
Stage, commit, and sync — pull, push, and fetch per repo, plus Fetch All / Pull All across every tracked repo at once
Diff view with hunk staging — unified diffs for files and commits in a side inspector; stage or unstage one hunk at a time
Per-repo auto-fetch — each repo on its own interval, on a background lane that never delays anything you do yourself
Auto-rebase on rejected push — opt-in per repo: a rejected push runs git pull --rebase --autostash and retries once
Undo for pull and auto-rebase — HEAD snapshotted to a ref first; restore with git reset --keep, never --hard
Repo groups, pinning, and a ⌘K command palette for getting around a big sidebar fast
Stash support, GitHub PR/CI badges (via gh, entirely optional), and an optional menu-bar mode
In-window command runner — a docked pane running shell commands in the repo's directory, output streamed live
History search by commit message, author, file path, or content (git's pickaxe search)
Themes — System/Light/Dark, custom accent color, fonts, and font size (⌘,)

The Stack

RepoDeck is Swift Package Manager only — there's no .xcodeproj, no .pbxproj to merge-conflict over. swift build, swift test, swift run RepoDeck are the entire dev loop.

The UI is SwiftUI, state is @Observable, and the codebase builds under Swift 6's strict concurrency checking.

The one deliberate architectural choice worth calling out: RepoDeck shells out to the real git binary instead of linking libgit2. That's slower per call, but it means every operation inherits the user's actual ~/.gitconfig — credential helpers, aliases, hooks, SSH config, everything — for free. It's the same reason VS Code's Source Control panel, GitHub Desktop, and lazygit all do the same thing: reimplementing what real git already does correctly, and what your credential helper already knows how to do, is a losing trade.

The package builds two targets: RepoDeckKit — every bit of git, parsing, and filesystem-watching logic, with no SwiftUI imports — and RepoDeck, the app target, which is just views and view models wired to it. Nothing in RepoDeckKit touches a window or the screen; every git call and every filesystem event passes through a seam a test can drive directly. That split is why the code below is unit- and integration-testable at all.

Parsing `git status --porcelain=v2 -z`

Status parsing runs on git status --porcelain=v2 --branch --untracked-files=all -z — NUL-separated so filenames with spaces, newlines, or anything else don't need escaping. PorcelainParser is a pure function over Data, no Process, no I/O, which makes it trivial to unit test without ever invoking git.

The XY fan-out

Porcelain v2's ordinary-change records carry a two-letter XY code: X is the index status, Y is the worktree status. A file that's staged and has further unstaged edits is one record, but RepoDeck's UI wants it in two different sections — Staged and Changes. appendFanOut does the split:

private static func appendFanOut(xy: Substring, path: String, originalPath: String?, into changes: inout [FileChange]) {
    let letters = Array(xy)
    guard letters.count == 2 else { return }
    let indexStatus = letters[0]
    let worktreeStatus = letters[1]
    if indexStatus != "." {
        changes.append(FileChange(path: path, originalPath: originalPath, area: .staged, statusLetter: String(indexStatus)))
    }
    if worktreeStatus != "." {
        changes.append(FileChange(path: path, originalPath: originalPath, area: .unstaged, statusLetter: String(worktreeStatus)))
    }
}

One record becomes zero, one, or two FileChange rows depending on which half of XY isn't a dot.

Renames consume the next token

Rename and copy records (2 ...) are the one record kind where a single logical event spans two NUL-delimited tokens: the record itself, then the original path as a separate token immediately after it. The dispatch loop has to know to look ahead and skip an extra slot:

case "2":
    let originalPath = index + 1 < records.count ? records[index + 1] : nil
    parseRenameOrCopy(record, originalPath: originalPath, into: &changes)
    index += originalPath != nil ? 2 : 1

Miss that index += 2 and the parser starts reading the next file's rename-origin path as if it were a new status record — everything after the first rename in the list comes out garbled.

Untracked files and merge conflicts

Two more record kinds skip the fan-out entirely. Untracked files (? records) are just the path after a fixed two-character prefix:

private static func parseUntracked(_ record: String, into changes: inout [FileChange]) {
    guard record.count > 2 else { return }
    let path = String(record.dropFirst(2)) // drop "? "
    changes.append(FileChange(path: path, area: .untracked, statusLetter: "U"))
}

Unmerged conflicts (u records, left behind by a failed merge or rebase) carry their own two-character conflict code and go straight into a dedicated .unmerged area rather than through the staged/unstaged split — a conflicted file isn't meaningfully "staged," it's blocking, and the UI treats it that way.

ProcessRunner: One Subprocess Primitive for Everything

Every git invocation in the app funnels through a single function: async, deadlock-free, cancellable, and globally bounded. Two rules made that worth centralizing instead of calling Process ad hoc wherever a view model needed git.

The pipe-drain deadlock

Pipes have a fixed OS buffer. Wait for a child process to exit before reading its stdout, and if that process writes more output than the pipe can hold, the child blocks writing while you're blocked waiting for it to exit — a real deadlock, and it only shows up once git status output gets big enough to fill the pipe. ProcessRunner drains stdout and stderr concurrently, in a loop, while the process is still running:

async let stderrData = drainAll(stderrStream)

var stdoutData = Data()
var truncated = false
for await chunk in stdoutStream {
    stdoutData.append(chunk)
    if let cap = maxOutputBytes, stdoutData.count >= cap {
        truncated = true
        process.terminate()
        break
    }
}

Only after both streams are fully drained does it wait for the actual process exit. The output cap lives in the same loop — once it's hit, the process is terminated on the spot rather than left to keep filling a pipe nobody will finish reading.

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore

Every subprocess runs with GIT_TERMINAL_PROMPT=0 so a missing credential fails fast with a real error instead of git silently hanging on a terminal prompt that will never appear in a GUI app:

var env = ProcessInfo.processInfo.environment
env["GIT_TERMINAL_PROMPT"] = "0"
env["LC_ALL"] = "C"

And because bulk operations (Fetch All, Pull All) can fire dozens of git processes at once, a process-wide counting semaphore caps concurrency at 6:

static let concurrencyLimit = 6
static let limiter = ConcurrencyLimiter(limit: concurrencyLimit)

Every ProcessRunner.run call acquires a slot before launching and releases it on every exit path — success, failure, or cancellation.

(Since 1.3.0 that semaphore is two-tier: background work — auto-fetch, PR/CI polling — can hold at most 4 of the 6 slots, and interactive work you triggered jumps ahead of queued background work. Network calls also carry a SIGTERM-then-SIGKILL watchdog timeout, so a hung remote can't pin a slot forever.)

Cancellation kills the child, not just the `Task`

Cancelling the surrounding Swift Task — closing a repo, navigating away mid-fetch — has to actually kill the git process, not just stop awaiting it and leave it running orphaned in the background:

} onCancel: {
    kill(pid, SIGTERM)
}

Process itself isn't Sendable, so only the pid — captured before entering the cancellation handler — is allowed to cross into that @Sendable closure. The drain loops then end naturally once the killed child closes its pipes.

Watching the Filesystem Without Hammering It

RepoDeck doesn't poll. RepoWatcher wraps the FSEvents C API directly and emits debounced events on an AsyncStream.

Ignoring `index.lock` churn

Git itself writes and deletes .git/index.lock constantly during normal operations — every git add, every git commit touches it. Without filtering that out, RepoDeck would refresh its own view of a repo's status in response to changes caused by its own git calls:

static func shouldIgnore(_ rawPath: String) -> Bool {
    let components = rawPath.split(separator: "/", omittingEmptySubsequences: true).map(String.init)
    if components.last == "index.lock", components.contains(".git") {
        return true
    }
    for component in components {
        if component.contains(".watchman-cookie") { return true }
        if prunedNames.contains(component) { return true }
    }
    return false
}

A 300ms debounce — no timer hammering your disk

Saving a file, running a build, or checking out a branch can fire dozens of FSEvents callbacks in a fraction of a second. RepoWatcher collapses a burst for the same repo into a single emission, 300ms after the last event in the burst — cancel-and-reschedule, not a recurring poll:

private func schedule(_ event: WatchEvent, key: String) {
    debounce[key]?.cancel()
    let item = DispatchWorkItem { [weak self] in
        guard let self else { return }
        self.debounce[key] = nil
        guard !self.stopped else { return }
        self.continuation.yield(event)
    }
    debounce[key] = item
    queue.asyncAfter(deadline: .now() + Self.debounceInterval, execute: item)
}

There's no timer running in the background polling anything. The app is silent until FSEvents says something changed, and even then it waits out the burst before doing a single git status.

The Truncation Seam

This is the bug I'm most annoyed I didn't catch sooner, because both halves of it were individually correct — and individually unit tested.

ProcessRunner's output cap protects against a repo with hundreds of thousands of untracked files turning git status into an unbounded memory sink: past the cap, it sends SIGTERM to the child and returns whatever was read, flagged as truncated. That's correct, and the unit tests for ProcessRunner confirmed it.

GitClient.status passes a truncated read through to PorcelainParser, which drops the trailing partial record and sets didHitLimit on the result. Also correct, also unit tested.

Here's the seam: SIGTERM makes the process's exit code come back as 15, not 0. And the shared helper that every GitClient method funneled through had one guard for all of them:

guard result.exitCode == 0 else {
    throw GitError(command: commandString(fullArguments), exitCode: result.exitCode, stderr: result.stderr)
}

A truncated status never reached PorcelainParser at all — it was thrown as a generic GitError before the parser ever saw the bytes. Which meant the "Too many changes — showing a partial list" banner in the Changes list, built and unit tested against a RepoStatus with didHitLimit == true, was unreachable in the running app. Every real truncation just looked like git had failed outright.

Nothing caught this in isolation, because nothing in isolation was wrong. ProcessRunner's truncation tests never touched GitClient. PorcelainParser's truncation tests fed it pre-truncated bytes directly, never through a real process exit code. The only place the seam existed was the exact path connecting a real SIGTERM, a real exit code 15, and that exit-code guard — and that only shows up in an end-to-end pass, not a unit test of either side alone.

The fix was widening one guard: result.exitCode == 0 || result.outputTruncated. Only status ever passes an output cap, so no other command's real failures get masked. To lock the seam shut for good, the status output cap became an injectable public property (4 MB by default) so a test could shrink it to 64 bytes against a real temporary repo with real files on disk — forcing an actual truncation, actual SIGTERM, actual exit 15, without generating megabytes of fixture data:

var client = GitClient()
client.statusOutputLimit = 64

let status = try await client.status(in: repo)
#expect(status.didHitLimit == true)

The lesson stuck: when two components are each individually correct and each individually tested, that says nothing about the seam between them. A whole-codebase review pass is what caught it — not either of the unit suites, which had been green the entire time. If a bug can only exist in the handoff, only a test that exercises that exact handoff will ever find it.

Five Releases Later

Since launch, RepoDeck has gone from a status dashboard to something closer to a daily driver: 1.3.0 added a per-repo settings sheet, per-repo auto-fetch intervals, sidebar groups, a ⌘K command palette, and opt-in auto-rebase on rejected pushes; 1.4.0 added one-level undo for pulls, stash support, GitHub PR/CI badges (via the gh CLI — the app's only non-git subprocess, and entirely optional), and a menu-bar mode; 1.5.0 brought a unified diff view; 1.6.0 an in-window command runner; and 1.7.0 finished the diff view with per-hunk staging.

The full per-release detail is in the changelog, and the README carries a release history and roadmap.

Build & Install

Easiest: download RepoDeck.dmg directly (or browse the latest release), open it, and drag RepoDeck onto Applications. It's ad-hoc signed, not notarized, so the first launch needs one manual nudge past Gatekeeper — right-click RepoDeck.app → Open, or:

xattr -dr com.apple.quarantine /Applications/RepoDeck.app

From source — Swift Package Manager only, no Xcode project needed:

git clone git@github.com:sergio-farfan/repodeck.git
cd repodeck
swift build
swift test
swift run RepoDeck

Full build, packaging, and release commands are in the README.

Source Code

RepoDeck is on GitHub: github.com/sergio-farfan/repodeck.

Built with Swift 6 and SwiftUI on macOS.

NoSleep: Prevent your Mac to go sleep. Period.

Sergio Farfan Cardenete — Sun, 22 Mar 2026 05:09:02 +0000

Have you ever been mid-presentation, watching a long build compile, or waiting for a large file to download — only for your Mac to decide it's nap time? macOS ships a built-in tool for exactly this: caffeinate. But running it from the terminal every time is clunky.

So I built NoSleep — a tiny macOS menu bar utility that wraps caffeinate in a one-click toggle. No Dock icon. No main window. Just a cup icon in your menu bar.

Update — v1.1.0: NoSleep now ships as a downloadable, drag-to-install .dmg (universal), activates the moment you pick a duration, shows a green active indicator with a readable countdown, and pops a notification with a one-tap Extend 1 hour when a timed session ends. The new bits — and the async race the notification introduced — are covered in the v1.1.0 section below.

Features

Download & run — grab the .dmg from Releases and drag NoSleep to Applications (universal: Apple Silicon + Intel)
One-click toggle — start/stop caffeinate from the menu bar
Auto-activate — pick a duration and it starts immediately, no extra click
Duration presets — 15 min, 30 min, 1 hr, 2 hr, 4 hr, 8 hr, 10 hr, or Indefinite
Live countdown — a green active dot and remaining time while active (e.g. 2h 34m)
Completion notification — when a timed session ends, a notification offers a one-tap Extend 1 hour
Start at Login — optional LaunchAgent so it auto-starts on boot
Prevents display + idle sleep — uses caffeinate -d -i

The Stack

Swift 6.0 with strict concurrency
SwiftUI + MenuBarExtra (macOS 13+)
UserNotifications — for the session-complete alert and its Extend action
Swift Package Manager — no Xcode project file required; ships a universal binary
Minimum target: macOS 14 (Sonoma)

App Entry Point: MenuBarExtra

The entire app lives in the menu bar, which SwiftUI makes surprisingly clean with MenuBarExtra:

@main
struct NoSleepApp: App {
    @StateObject private var caffeinateManager = CaffeinateManager()
    @StateObject private var loginManager = LoginItemManager()

    var body: some Scene {
        MenuBarExtra {
            MenuBarView(manager: caffeinateManager, loginManager: loginManager)
        } label: {
            Image(systemName: caffeinateManager.isActive
                  ? "cup.and.saucer.fill"
                  : "cup.and.saucer")
        }
    }
}

That's the whole entry point. MenuBarExtra handles all the menu bar plumbing — no NSStatusItem, no AppKit boilerplate. The icon toggles between a filled and outlined cup based on whether caffeinate is running.

Setting LSUIElement: true in Info.plist hides the Dock icon and removes the main window entirely.

Core Logic: CaffeinateManager

The heart of the app is CaffeinateManager — an @MainActor ObservableObject that manages the caffeinate child process and a countdown timer.

Spawning the Process

func start() {
    stop()

    let proc = Process()
    proc.executableURL = URL(fileURLWithPath: "/usr/bin/caffeinate")

    var args = ["-d", "-i"]
    if selectedDuration != .indefinite {
        args += ["-t", "\(selectedDuration.rawValue)"]
        remainingSeconds = selectedDuration.rawValue
    }
    proc.arguments = args

    proc.terminationHandler = { [weak self] _ in
        Task { @MainActor [weak self] in
            self?.handleTermination()
        }
    }

    try? proc.run()
    process = proc
    isActive = true

    if selectedDuration != .indefinite {
        timer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { [weak self] _ in
            Task { @MainActor [weak self] in
                self?.tick()
            }
        }
    }
}

A few things worth noting:

-d -i flags — -d prevents the display from sleeping, -i prevents idle sleep. Together they cover the common use cases.

-t <seconds> — when a duration is selected, caffeinate self-terminates after that many seconds. The app also runs a Timer in parallel to track remaining time for the UI.

terminationHandler — if caffeinate exits on its own (duration expired, or the system killed it), this handler fires and cleans up app state. The Task { @MainActor in ... } pattern bridges from the background callback thread into the main actor, which Swift 6 strict concurrency requires. (In v1.1.0 this handler grew a run-token guard — more on why below.)

Duration Options

Durations are a typed enum with raw values in seconds:

enum SleepDuration: Int, CaseIterable, Identifiable, Sendable {
    case fifteenMin = 900
    case thirtyMin  = 1800
    case oneHour    = 3600
    case twoHours   = 7200
    case fourHours  = 14400
    case eightHours = 28800
    case tenHours   = 36000
    case indefinite = 0
}

The selected duration is persisted in UserDefaults so the preference survives app restarts.

Login Item: LaunchAgent Plist

Rather than using SMAppService (which requires a sandboxed app), NoSleep writes a LaunchAgent plist directly to ~/Library/LaunchAgents/:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.nosleep.app</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/you/Applications/NoSleep.app/Contents/MacOS/NoSleep</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

This approach works without sandboxing and gives full control over the plist.

v1.1.0: Auto-Activate, Completion Alerts, and a Real Download

Pick a duration → it just starts

Originally you picked a duration and then clicked Start. Now selecting any preset activates immediately:

func changeDuration(_ duration: SleepDuration) {
    selectedDuration = duration
    start()   // auto-activate on selection (re-selecting restarts the timer)
}

A completion notification you can act on

When a timed session ends, NoSleep posts a notification with an Extend 1 hour action, using UserNotifications:

let extend = UNNotificationAction(identifier: "EXTEND_1H",
                                  title: "Extend 1 hour", options: [])
let category = UNNotificationCategory(identifier: "SESSION_COMPLETE",
                                      actions: [extend],
                                      intentIdentifiers: [], options: [])
UNUserNotificationCenter.current().setNotificationCategories([category])

Tapping Extend 1 hour starts a fresh one-hour session. One gotcha: the delegate has to be registered at launch — Apple requires it before the app finishes launching, so doing it lazily when the menu first opens can drop the action response.

The stale-termination trap

Here's the interesting bug the notification surfaced. caffeinate runs as a child process; when it exits, its terminationHandler fires on a background thread. But that handler fires for three different reasons: the timer expired (→ notify), the user hit Stop (→ don't notify), or a restart replaced the process (→ don't notify, and don't clobber the new session's state).

The restart case is a classic async race: start() calls stop() (terminating the old process), then launches a new one — but the old process's termination callback arrives later, after the new session is already live. A naive "was this a user stop?" flag misfires.

The fix is a monotonic run token. Each start() bumps a counter, and the termination handler captures the value it was launched with:

func start() {
    stop()
    runToken += 1
    let token = runToken
    // ...spawn caffeinate...
    proc.terminationHandler = { [weak self] _ in
        Task { @MainActor [weak self] in self?.handleTermination(token: token) }
    }
}

private func handleTermination(token: Int) {
    guard token == runToken else { return }   // stale (restarted) — ignore it
    // ...decide natural-expiry vs user-stop, then maybe post the notification
}

Because the main actor runs start() synchronously through the token bump, any stale handler that arrives afterward sees a token that no longer matches — and bails out before touching the new session or firing a notification. The whole "should this fire?" decision is a small pure function, which made it easy to unit-test in isolation.

Download-and-run distribution

The biggest change for users: NoSleep now ships a real .dmg. The entire pipeline uses only tooling that's already on every Mac — no third-party dependencies:

App icon — a small AppKit script renders the cup.and.saucer.fill SF Symbol onto a gradient squircle, then sips + iconutil turn it into AppIcon.icns.
Universal binary — swift build -c release --arch arm64 --arch x86_64.
Styled DMG — hdiutil plus a little AppleScript lay out the window: the app on the left, an arrow to an Applications drop-target, a background image, and a volume icon.

Because it's ad-hoc signed (not notarized), the first launch needs a one-time Gatekeeper nudge:

xattr -dr com.apple.quarantine /Applications/NoSleep.app

Build & Install

Easiest: download NoSleep-<version>.dmg from the latest release, open it, and drag NoSleep onto Applications. On first launch, run the xattr command above (or right-click → Open) once.

From source — the project uses Swift Package Manager, no .xcodeproj needed:

# Build (universal binary, bundles, ad-hoc code signs)
./build.sh

# Run
open NoSleep.app

# Package a distributable .dmg
./package-dmg.sh

# Install to ~/Applications (optional)
./install.sh

Requirements to build: Swift 6.0+, Xcode Command Line Tools, macOS 14+.

Source Code

NoSleep is open source under the GPLv3.

GitHub: github.com/sergio-farfan/nosleep

Contributions, issues, and stars are all welcome. If you run into any macOS quirks with caffeinate, MenuBarExtra, or notifications from an ad-hoc-signed app, feel free to open an issue.

Built with Swift 6 and SwiftUI on macOS Sonoma.

I Built a Windows-Style Alt+Tab Window Switcher for macOS in Pure Swift

Sergio Farfan Cardenete — Sun, 22 Mar 2026 04:16:11 +0000

What It Does

Hold Option and tap Tab — a panel appears showing every open window across all your apps, on the screen where your mouse is. Cycle through them with Tab / Shift-Tab or the arrow keys, then release Option to jump straight to the selected window. Click any thumbnail to switch instantly.

Shortcut	Action
`Option-Tab`	Open switcher / next window
`Tab`	Cycle forward
`Shift-Tab`	Cycle backward
`← / →`	Navigate left / right
`Escape`	Cancel
`Enter`	Confirm and switch
Click	Select and switch immediately

The switcher includes minimized windows (they unminimize when selected), windows of Cmd-H-hidden apps, and windows sitting on other Spaces. No Dock icon, no clutter — just a clean menu bar icon with a small preferences menu.

What's New in 1.3

Liquid Glass. On macOS 26 (Tahoe), the switcher can render on Apple's native glass material via NSGlassEffectView — the real thing, not a blur imitation. Status menu → Background → Liquid Glass.
Selectable backgrounds. Three styles, applied on the next Option-Tab with no relaunch: Solid (default — opaque, theme-adaptive), Transparent (the classic translucent HUD with vibrancy), and Liquid Glass.
Appearance override. The panel follows the OS Light/Dark theme by default (including scheduled Auto switching), and you can force Light or Dark from the menu regardless of the system setting.
WCAG-tested readability. The text under each window is no longer hardcoded white on a translucent panel. Labels use semantic system colors, and on the default Solid background the label/background pair meets WCAG 2.x AA (contrast ≥ 4.5:1) — not as an aspiration, but verified by unit tests that resolve the live system colors under both Light and Dark appearances and compute the actual contrast ratio. If Apple ever changes the palette in a way that breaks AA, the test suite fails.

What's New in 1.2

Instant-open switcher (cached window list, reconciled off the main thread), a 0.25s messaging timeout on every Accessibility call so one wedged app can't freeze the hotkey, opt-in live window previews via ScreenCaptureKit (macOS 14+, no Screen Recording prompt unless you enable it), click-to-switch fixed, multi-monitor support, and a unit-tested core.

Installation

Requirements: macOS 13 Ventura or later (Liquid Glass needs macOS 26)

Download (recommended)

Grab the prebuilt universal DMG (Apple Silicon + Intel) from the releases page, drag AltTab to Applications, and launch it. The build is not notarized yet, so on first launch: right-click AltTab.app → Open, or

xattr -dr com.apple.quarantine /Applications/AltTab.app

Build from source

git clone https://github.com/sergio-farfan/alttab-macos.git && cd alttab-macos && ./build.sh install && open ~/Applications/AltTab.app

./build.sh build          # Build Release binary only
./build.sh install        # Build and install to ~/Applications
./build.sh run            # Build and launch immediately
./build.sh uninstall      # Remove the installed app
swift test                # Run the unit tests (32)

Note: building the Liquid Glass code requires Xcode 26+ (macOS 26 SDK); the app still runs on macOS 13+.

Permissions

Accessibility (required) — intercepts the Option-Tab hotkey, reads window titles, raises windows
Screen Recording (never prompted by default) — only requested if you explicitly enable "Show Window Previews" in the menu

How It Works

Global hotkey interception — A CGEvent tap installed at the session level intercepts Option-Tab system-wide before it reaches any app, without stealing keyboard focus. The tap plumbing only decodes events; the session logic lives in a pure SwitcherStateMachine struct, unit-testable without synthesizing CGEvents.

Complete window discovery — On-screen windows come from CGWindowList. Everything else (titles, minimized windows, hidden apps, other Spaces) comes from a single AXUIElement pass per application, with a messaging timeout on every element. Fun fact: AXUIElementSetMessagingTimeout is per-element — setting it on the app element does nothing for the window elements it returns.

Selectable backgrounds — The panel builds one of three root views per style: an opaque NSBox (Solid), a .hudWindow NSVisualEffectView (Transparent — labels become effect-view descendants, so macOS renders them with vibrancy), or an NSGlassEffectView (Liquid Glass) with the content embedded through its contentView property, which is the only placement the SDK header guarantees. The persistent scroll view is re-parented between roots only when the preference actually changes.

MRU ordering — Windows are sorted most-recently-used first via NSWorkspace notifications plus per-app AXObserver callbacks that catch intra-app switches (like Cmd-`). Explicit activations are pinned so the asynchronous window-raise can't demote the window you just picked.

Non-activating overlay — The switcher is an NSPanel with .nonactivatingPanel, so it appears without stealing focus. Releasing Option activates the target window, not AltTab.

Two More macOS Gotchas

The 1.3 work surfaced two API behaviors worth knowing about.

withAlphaComponent() freezes dynamic colors. macOS semantic colors like labelColor are dynamic — they resolve differently per appearance, at draw time. But call withAlphaComponent(0.78) on one and you get back a static color, resolved against whatever appearance happens to be current at that call site. My unit test caught this before it shipped: the derived color measured 1.21:1 contrast in Dark mode — because it had frozen the Light variant (black text) and composited it onto a dark background. The fix is NSColor(name:dynamicProvider:), which re-derives the color inside each appearance resolution. If you take one thing from this post: contrast assertions in unit tests that resolve live system colors are cheap, and they catch exactly this class of bug.

#available gates runtime, not compile time. The Liquid Glass code is properly wrapped in #available(macOS 26.0, *) — and the release build still failed in CI with cannot find 'NSGlassEffectView' in scope. Locally everything compiled fine. The difference: my Mac has the macOS 26 SDK; the CI runner had Xcode 16 with the macOS 15 SDK, where the symbol doesn't exist at all. Availability checks assume the symbol is in the SDK you compile against — they only guard which OS executes it. Bumping the CI image to one with Xcode 26 fixed it. If you adopt Tahoe APIs behind #available, check your CI's SDK before you tag the release.

When the Accessibility Toggle Lies

(From the 1.2.1 investigation, still the best bug of this project.) After updating, Option-Tab went dead while System Settings showed the Accessibility toggle confidently ON. macOS pins every TCC permission grant to a code signing requirement — for unsigned apps, essentially the cdhash of one exact build. My DMG script built with CODE_SIGNING_ALLOWED=NO, which ships an unsealed bundle, and macOS fabricates unpredictable code identities for those — so the recorded grant never matched the running binary. The toggle renders "an allowed entry exists"; enforcement asks "does this binary match the requirement". Different questions.

Diagnosing it meant reading the csreq blob out of TCC.db with sqlite3, decompiling it with csreq -r -t, comparing cdhashes with codesign -dvvv, and confirming with CGGetEventTapList that no event tap existed. The fix: always apply an ad-hoc seal (codesign --force --deep -s -) when no signing identity is available. If you ever hit a stuck grant on an unsigned app:

tccutil reset Accessibility <bundle-id>

then relaunch and grant again.

Project Stats

~2,100 lines of Swift across 13 source files, plus a unit-tested core (32 tests, swift test)
Zero external dependencies — pure Swift + AppKit + ScreenCaptureKit
MIT licensed — fork it, modify it, ship it
macOS 13+ (Ventura through Tahoe; Liquid Glass on 26+)

Try It Out

The code is on GitHub: github.com/sergio-farfan/alttab-macos

If you have been frustrated by macOS window switching, give it a try. And if you are curious about the low-level macOS APIs — CGEvent taps, AXUIElement, ScreenCaptureKit, NSGlassEffectView, or how TCC really decides whether your app is trusted — the codebase is small enough to read in an afternoon.

Feedback, issues, and PRs are welcome!

Generate OCI Architecture Diagrams from Terraform with One Claude Code Command

Sergio Farfan Cardenete — Tue, 17 Mar 2026 01:16:57 +0000

Update (Jul 2026): v1.1.0 is out — aspect-correct icons, the official Oracle v24.2 palette and container styles, orthogonal edge routing by default, and a shipped overlap checker. Existing scripts keep running unchanged. See "What's new in v1.1.0" below, or jump straight to the release notes.

The problem

Manually drawing OCI diagrams in draw.io is tedious...
If you have ever had to document an OCI architecture, the process is familiar. You open draw.io, locate the correct Oracle icon set, drag shapes onto the canvas, manually wire up VCNs and subnets, nudge elements into alignment — then spend another 30 minutes reconciling colors against Oracle's official template, only to discover that the Terraform configuration changed the previous week and the diagram is already out of date.

For cloud architects working with OCI, this is a recurring overhead on every project:

Diagrams drift from reality

Terraform is the source of truth, but draw.io has no awareness of it. Every infrastructure change requires a manual diagram update — one that typically does not occur until someone requests it during a review.

The OCI icon set is not native to draw.io

It must be located, imported, and mapped to the correct services across 15 categories and 220+ icons — a non-trivial exercise before any actual diagramming begins.

Layout is time-consuming

Correctly representing the Region → VCN → Subnet → Service hierarchy, with proper spacing, non-overlapping containers, and Oracle's color scheme, requires significant effort even for experienced practitioners.

Hub-and-spoke topologies are especially difficult

Arranging 10–15 spoke VCNs connected through a DRG in a clean, readable layout is an hour-long exercise in manual positioning.

Diagrams are created once and abandoned

Because updates are costly, teams stop maintaining them. By the time a new team member onboards or an audit is conducted, the diagram reflects an architecture from two sprints prior.

The root cause is that architecture diagrams are treated as design artifacts — something produced manually — rather than something derived directly from the infrastructure definition.

What I built

https://github.com/sergio-farfan/OCI-draw.io-Architect

A Claude Code plugin — type /drawio-architect in any project...

How it works

The plugin accepts three input types: a Terraform directory path — parsed to extract VCNs, subnets, gateways, and DRG attachments — a VCN name resolved against existing .tfvars files, or a plain-text description of the target architecture.

From any of these inputs, it computes a pixel-precise grid layout, calculating container bounding boxes to eliminate element overlap, and generates a Python script leveraging a custom DrawioBuilder class backed by 220 bundled OCI SVG icons. Executing the script produces a .drawio file fully styled with Oracle's official color palette.

The entire workflow is invoked within Claude Code via a single /drawio-architect command.

Step by Step Installation

Prerequisites

Claude Code (CLI) installed and working
Python 3.9+
draw.io desktop for viewing generated .drawio files

The plugin bundles 220 OCI SVG icons and auto-installs Pillow (Python imaging library) if missing.

Installation

Step 1 - Download, Extract and Install

One command:

curl -fsSL https://github.com/sergio-farfan/OCI-draw.io-Architect/releases/download/v1.1.0/oci-drawio-architect-v1.1.0.tar.gz | tar -xz && ./oci-drawio-architect/install.sh

This will:

Download, extract and execute the Installer script
Check prerequisites (Python 3, Pillow)
Install Pillow automatically if missing
Create a local marketplace at ~/.claude/plugins/marketplaces/local/
Copy the plugin files into the marketplace
Verify all components (5 checks)

Step 2 - Register in Claude Code

Open Claude Code and run these two commands:

/plugin marketplace add ~/.claude/plugins/marketplaces/local
/plugin install oci-drawio-architect@local

Exit Claude Code and reopen it for the plugin to load.

Step 3 - Verify

Run inside Claude Code:

/drawio-architect

The command should prompt you for what to diagram.

Example Snippet:

What's new in v1.1.0

I've kept using this plugin since I posted this, and v1.1.0 is a big step up in rendering fidelity and workflow safety. Here's what changed.

Aspect-correct icons. v1.0.0 forced every icon into a fixed 75x95 slot, which stretched non-square icons by 15-20% on one axis. v1.1.0 reads each SVG's native aspect ratio and derives the cell size from it — fixed 95px height, width computed from the icon's own proportions (or the other way around if you only pass w or h to add_icon()). Icons render true to their actual shape now.

Styles aligned to Oracle's official v24.2 toolkit, plus 5 new container types. The color palette and every container style are now extracted directly from Oracle's official OCI Architecture Diagram Toolkit (v24.2): dotted-Sienna compartments with Bark labels, a #9E9892 2pt services-panel border, centered region labels, plain dashed connectors. Five new group types fill out the container vocabulary: tenancy, availability_domain, fault_domain, oracle_services_network, and onprem (the old hub type still works — it's now a deprecated alias of onprem).

Orthogonal edge routing by default. Port-less add_edge() calls now hand routing to draw.io's own orthogonal router instead of pinning a fixed exit/entry side. You get cleaner, auto-routed connectors without touching your script.

Before (v1.0.0, pinned ports on every edge):

d.add_edge(lb, vm, "443", parent=vcn,
           exit_x=1.0, exit_y=0.5, entry_x=0.0, entry_y=0.5)

After (v1.1.0, default — let draw.io route it):

d.add_edge(lb, vm, "443", parent=vcn)

Scripts that still pass exit_x/exit_y/entry_x/entry_y or waypoints keep their exact v1.0.0 pinned behavior — nothing breaks.

A shipped overlap checker, now a workflow gate. scripts/check_overlaps.py is a standalone CLI (exit 0 clean, 1 overlaps found, 2 usage/parse error), backed by DrawioBuilder.check_overlaps(). The /drawio-architect command now runs it as a mandatory gate before handing you the .drawio file, so overlapping containers get caught before you open draw.io, not after.

Metadata and tooltips. add_icon() and add_group() take optional metadata= and tooltip= arguments now, stored as draw.io <object> attributes. Hover a shape in draw.io to see the tooltip, or open Edit Data to see the metadata — useful for attaching OCIDs, workload tags, or anything else you want to keep with a shape.

detect_settings hardening. The Terraform-directory and tenancy-detection logic got a pass: the tenancy-OCID regex is now bounded (no more cross-variable false matches), Terraform-directory discovery is deterministic, OCI CLI JSON handling is more robust, and there's an optional plugin-local logos/ directory for embedding your own logo in a diagram.

A real demo. examples/generate_demo_diagram.py builds a full sample architecture — tenancy → on-prem + region → availability/fault domains, compartment → VCN → subnets, a services panel, an Oracle Services Network panel — exercising every container type, the main icon-sizing and edge modes, metadata/tooltips, and the overlap gate in one script. It doubles as a post-install smoke test.

Python 3.9 is now the floor (was 3.8).

Compatibility

Existing v1.0.0 scripts run unchanged — positional arguments, keyword ports plus waypoints, and the hub group type are all preserved. Regenerated diagrams will pick up the refreshed v24.2 styling and aspect-correct icons automatically.

Full release notes: https://github.com/sergio-farfan/OCI-draw.io-Architect/releases/tag/v1.1.0

DEV Community: Sergio Farfan Cardenete

Apple Music Consolidator: merge and dedupe hundreds of Apple Music playlists, safely

Now try fixing that by hand

"Isn't there a tool for this?"

What It Does

How It Works

Take It for a Test Drive

Build & Install

Source Code

RepoDeck: a native macOS dashboard for all your git repos

Features

The Stack

Parsing git status --porcelain=v2 -z

The XY fan-out

Renames consume the next token

Untracked files and merge conflicts

ProcessRunner: One Subprocess Primitive for Everything

The pipe-drain deadlock

GIT_TERMINAL_PROMPT=0 and a 6-slot semaphore

Cancellation kills the child, not just the Task

Watching the Filesystem Without Hammering It

Ignoring index.lock churn

A 300ms debounce — no timer hammering your disk

The Truncation Seam

Five Releases Later

Build & Install

Source Code

NoSleep: Prevent your Mac to go sleep. Period.

Features

The Stack

App Entry Point: MenuBarExtra

Core Logic: CaffeinateManager

Spawning the Process

Duration Options

Login Item: LaunchAgent Plist

v1.1.0: Auto-Activate, Completion Alerts, and a Real Download

Pick a duration → it just starts

A completion notification you can act on

The stale-termination trap

Download-and-run distribution

Build & Install

Source Code

I Built a Windows-Style Alt+Tab Window Switcher for macOS in Pure Swift

What It Does

What's New in 1.3

What's New in 1.2

Installation

Download (recommended)

Build from source

Permissions

How It Works

Two More macOS Gotchas

When the Accessibility Toggle Lies

Project Stats

Try It Out

Generate OCI Architecture Diagrams from Terraform with One Claude Code Command

The problem

Diagrams drift from reality

The OCI icon set is not native to draw.io

Layout is time-consuming

Hub-and-spoke topologies are especially difficult

Diagrams are created once and abandoned

What I built

How it works

Step by Step Installation

Prerequisites

Installation

Step 1 - Download, Extract and Install

Step 2 - Register in Claude Code

Step 3 - Verify

What's new in v1.1.0

Compatibility

Parsing `git status --porcelain=v2 -z`

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore

Cancellation kills the child, not just the `Task`

Ignoring `index.lock` churn