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. It now handles branches, worktrees, conflicts, and code reviews too, without losing that overview.

Updated September 2026: 1.11.0 is out as a stable release. This update adds readable messages with recovery actions, searchable offline Help, commit-author setup inside the app, and a fix for the diff-window layout crash reported on macOS 27. Making Errors Useful covers what changed; From Dashboard to Git Client explains the graph, branches, worktrees, conflicts, and reviews behind the current app.

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

Features

Multi-repo dashboard — track folders, discover repositories and their registered worktrees, and filter for changes, conflicts, ahead/behind state, or errors
Live status via FSEvents — filesystem-driven refreshes, including the separate Git metadata used by linked worktrees
Stage, commit, and sync — pull, push, and fetch per repo, plus Fetch All / Pull All with success, failure, and skipped counts plus per-repository results
Diff view with hunk staging — unified file and commit diffs; stage or unstage eligible text hunks, with whole-file alternatives when exact content or metadata cannot be preserved
Commit graph and history search — parent connections, branch/tag labels, current/all-branch views, 100-commit pages, and search by message, author, file path, or content
Branches and worktrees — create, switch, rename, safely delete merged branches, set tracking, and create, open, or safely remove worktrees
Text conflict workspace — base/current/incoming text, an editable result, separate Save and Mark Resolved, and operation-aware Continue / Abort controls
GitHub and GitLab reviews — browse PRs/MRs, file changes, discussion, and checks; create requests, comment, approve, merge, and check out a review into its own worktree, using optional gh / glab integrations
Per-repo auto-fetch — configurable intervals, a capped background lane, and priority for queued interactive work
Auto-rebase on rejected push — opt-in per repo: a rejected push runs git pull --rebase --autostash and retries once; conflicts or a retained autostash can still require recovery
Undo for pull and auto-rebase — restore the recorded commit with git reset --keep, bound to the original branch and worktree; this is not a backup of arbitrary local files
Repo groups, pinning, hiding/restoring repos, and a ⌘K command palette for getting around a big sidebar fast
Stash support, optional GitHub PR/CI badges, and an optional menu-bar mode
In-window command runner — shell commands in the repo's directory, bounded live output, and cancellation that cleans up the owned process group; open a terminal for interactive programs
Developer tool preferences — configurable Git/hosting executables, preferred editor and terminal, and per-repository overrides
Actionable messages — readable notices inside the workspace, recovery actions where available, and selectable, copyable diagnostic details
Offline Help — 18 searchable topics covering setup, everyday workflows, troubleshooting, and recovery
Commit-author setup — see the effective author Git will use, configure repository-specific or global defaults, and distinguish commit attribution from SSH and hosting authentication
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 current baseline is macOS 15+ and Swift 6.2+.

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 keeps ordinary Git configuration, credential helpers, hooks, and SSH setup in play. Machine-parsed commands set their own output options — a display filter or terminal color setting must not change the bytes that end up staged. I want the installed Git to do the Git work, with the app responsible for choosing the right command and explaining the result.

The package now has three main targets: RepoDeckKit contains Git execution, parsing, discovery, file watching, and hosting adapters; RepoDeckCore contains application and worktree state, scheduling, and refresh coordination; and RepoDeck contains the SwiftUI/AppKit presentation. Tests can inject clients, scanners, clocks, preferences, and watcher events without opening a window. That matters for bugs like an older refresh replacing a newer result, or a slow commit clearing a draft I've edited since pressing Commit.

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
    if let originalPath { 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

Git and hosting commands share one subprocess runner, with async entry points, bounded output, cancellation, and a global concurrency limit. The command pane uses the same machinery. The current implementation keeps the original reason for centralizing it, but the implementation now owns a POSIX process group for each job.

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 the output gets big enough.

The current worker uses nonblocking file descriptors and services both output streams while the child is running. These two calls sit in the same loop as cancellation, timeout, stdin, and exit handling:

readOutput(&outputFD, stream: .stdout, decoder: &outDecoder, data: &stdout)
readOutput(&errorFD, stream: .stderr, decoder: &errDecoder, data: &stderr)

The combined stdout/stderr budget defaults to 16 MiB, with smaller limits where a caller needs them. Exceeding the budget starts process-group shutdown. Pipe draining is bounded during shutdown too: a descendant holding an inherited pipe open must not turn a short timeout into a long wait. The blocking poll/exit-handling work runs off Swift's cooperative executor.

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore

The runner sets Git's terminal-prompt behavior and locale before applying any explicit caller overrides:

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

That prevents Git from waiting on its own username/password terminal prompt in a GUI operation. It doesn't make every external credential helper or hook noninteractive, so timeouts and useful errors still matter.

Bulk operations can fire dozens of commands at once, so a process-wide limiter caps concurrency at 6:

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

Background work can hold at most 4 of those slots; queued interactive work has priority. Acquisition itself is cancellable, cancellation is checked again before launch, and every acquired slot is released on success, failure, or cancellation. A running background job still uses resources — this is scheduling priority, not a promise that background work has zero cost.

Cancellation owns the whole job

Cancelling a Swift Task has to stop the command's work, not just stop awaiting its result. Killing only the parent process is insufficient when a child has inherited the output pipes. The runner creates a separate process group at launch, then starts shutdown with:

func beginStopping() {
    guard stoppingAt == nil else { return }
    stoppingAt = .now
    kill(-pid, SIGTERM)
    closeFD(&inputFD)
}

The negative PID targets the owned process group. Shutdown escalates to SIGKILL after 500 ms and closes remaining output pipes after one second; the leader is reaped before the job returns. A command's background children belong to that command's lifetime, so the command pane isn't a daemon launcher.

There's one more lifetime to keep straight: cancelling a stream consumer can end iteration before process cleanup finishes. The streaming handle exposes waitForCompletion(), and the command pane holds its repository coordination lock until cleanup is done. A stopped pane must not let the next Git mutation overlap a job that's still exiting.

Watching the Filesystem Without Hammering It

Local status refreshes are driven by FSEvents rather than a polling loop. RepoWatcher wraps the C API and emits debounced events on an AsyncStream. Optional auto-fetch and hosting refreshes are separate scheduled work; “event-driven status” doesn't mean the entire app has no timers.

Map the repository before filtering the path

Git writes and removes index.lock during index updates. Ignoring that lock-file churn avoids unnecessary refreshes, while the actual index and ref changes still matter. The watcher also ignores temporary watchman-cookie events.

The less obvious part is where filtering happens. An absolute path can contain a folder named vendor or target above a perfectly valid repository. Dropping the whole event because one component looks like a dependency directory makes that repository silently stop refreshing.

For a known repository, the watcher first computes a relative path:

let relative = String(path.dropFirst(repo.key.count))
guard !Self.shouldIgnore(relative, forKnownRepo: true) else { continue }

The filter only uses dependency/build-directory pruning for discovery paths, not changes inside a known repository:

for component in components {
    if component.contains(".watchman-cookie") { return true }
    if !forKnownRepo && prunedNames.contains(component) { return true }
}

Linked worktrees need another mapping: their Git directory and shared common directory can live outside the checkout. Those metadata paths are watched too, and a shared change can refresh every affected worktree. If FSEvents reports dropped events, the app schedules repository refreshes and folder discovery instead of assuming its current snapshot is complete.

A 300ms debounce — no timer hammering your disk

Saving a file, running a build, or checking out a branch can fire dozens of callbacks in a fraction of a second. A burst for the same repo collapses into a single emission about 300ms after the last event — cancel-and-reschedule, not a recurring status 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)
}

The state layer then coalesces rescans and rejects obsolete results. Relevant external Git changes also refresh history, stashes, open diffs, and review context — keeping a sidebar count current isn't enough if the open workspace still describes the old branch.

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.

The original ProcessRunner output cap protected against a repo with hundreds of thousands of untracked files turning git status into an unbounded memory sink: past the cap, it stopped the command and returned what had been captured, flagged as truncated. The unit tests for ProcessRunner covered that behavior.

GitClient.status was supposed to pass a truncated read through to PorcelainParser, which drops the trailing partial record and sets didHitLimit on the result. The parser behavior was also unit tested.

Here's the seam: stopping the command with SIGTERM could produce a signal exit of 15 instead of 0. The shared helper had this guard:

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

When output-limit shutdown produced a nonzero exit, the helper threw a generic GitError before PorcelainParser saw the bytes. The "Too many changes — showing a partial list" banner, built and unit tested against a RepoStatus with didHitLimit == true, therefore failed to appear in exactly that case. A usable partial result looked like an ordinary Git failure.

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 output-limit shutdown, a nonzero exit, 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 to let explicitly truncated output reach the caller instead of rejecting it solely because shutdown produced a nonzero exit. Status turns it into a partial list; diff operations reject oversized output instead of offering an incomplete patch. Timed-out results are errors. The runner now has a default cap for other commands too, so the truncation flag is part of the caller's contract, not a general sign of success.

The status cap remains injectable (4 MB by default). The integration test creates twenty untracked files and lowers the cap to 256 bytes — enough for some complete records, but not the whole list:

var client = GitClient()
client.statusOutputLimit = 256

let status = try await client.status(in: repo)
#expect(status.didHitLimit == true)
#expect(status.changes.count >= 1)
#expect(status.changes.count < 20)

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.

From Dashboard to Git Client

The early releases filled in the everyday gaps: per-repo auto-fetch, groups, a ⌘K palette, opt-in auto-rebase, undo, stashes, PR/CI badges, a menu-bar mode, diffs, and hunk staging. Later came the sidebar identity footer and hiding repositories without deleting their folders. 1.10.1 took the next step: I can move from noticing a repository needs attention to working through its branch, conflict, or review in the same app.

History, branches, and worktrees

History now includes a commit graph with parent connections and branch/tag decorations, current/all-branch views, and 100-commit pagination. Branch and worktree management sit alongside it. Discovery asks Git for its registered worktrees, so a linked sibling outside the folder I originally added can still appear in the dashboard.

A review checkout gets its own worktree, leaving the current checkout's files in place. Safe removal checks ignored and untracked files too — a clean-looking Git status must not be taken as permission to discard a local .env file. Selection, drafts, and review context belong to each worktree instead of whichever view happens to be mounted.

Conflicts and code review

The conflict workspace shows base, current, and incoming text with an editable result. Save and Mark Resolved are separate actions, and both check whether the file or index changed externally. Binary files, unsupported encodings, submodules, and complex conflicts use an external editor/terminal workflow instead of pretending everything is editable text.

GitHub and GitLab reviews use the optional gh and glab CLIs. Public and self-hosted destinations are represented explicitly; the preview identifies the account, repository, branches, and action before a write. Review lists, descriptions, changed files, discussion, checks, request creation, comments, approvals, and merge are available according to provider capabilities and server permissions. GitHub supports formal change-request reviews; GitLab currently offers comments and approvals for that part of the workflow.

A review can change while it's open. Approving or merging therefore rechecks the reviewed head. A failed write preserves the draft, and uncertain create/comment responses are reconciled before retrying, using the same operation identifier. Local Git workflows still work without either hosting CLI installed.

The safety work behind the buttons

A hunk-staging button is only useful if it stages exactly the bytes I selected. Partial operations now require lossless UTF-8 and supported file metadata, disable text conversion/external diff helpers/color, and revalidate the displayed diff before writing. Unsupported encodings, symlinks, submodules, renames, or mode changes get a visible whole-file alternative. Selected filenames are literal, so literal[1].txt doesn't accidentally select literal1.txt too.

Stash selections follow object IDs instead of trusting an old row number. Undo verifies the original worktree, branch, and expected commit. Mutations that share Git metadata are coordinated, and their previews are checked again after waiting for capacity. External Git programs don't participate in that coordination, so I don't describe this as an atomic transaction against every other process on the machine.

The 1.10.1 release also added safer icon-resource lookup: missing resources no longer invoke the fatal SwiftPM accessor during launch. Seven fixture scenarios cover packaged apps, executable-adjacent bundles, and absent resources. For the current 1.11.0 release source, native Apple silicon and Intel CI each passed 389 tests across 28 suites, alongside build and packaging checks. Both published DMG names were downloaded and checked against the release SHA-256; the app inside was verified for its version, universal architecture, and ad-hoc signature.

That still leaves work to validate on real setups: clean-machine installation and first launch, the full VoiceOver/appearance matrix, and live GitHub/GitLab writes across permissions and hosting configurations. Those limits are recorded in the release notes. Interactive rebase editing, inline threaded-review editing, issue tracking, and Windows/Linux ports remain future work.

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

Making Errors Useful

One of the most useful bug reports was also one of the simplest: a message was drawn across the top of the window, over the sidebar title, and I couldn't read it. Worse, a successful Fetch All was wearing a warning icon. Even a correct Git operation feels broken when the app explains it badly.

1.11.0 puts notices inside the workspace with bounded, wrapping text. Success, warning, and failure have distinct presentations. Longer diagnostics live in a scrollable details view where I can select and copy them, instead of stretching a banner across the window. When the failure is recognized, the app offers an appropriate next step — opening the relevant workspace, settings, terminal, or Help topic. It doesn't silently run a destructive command to make the message disappear.

Bulk operations also keep the result for each repository. If Pull All reports a failure or a busy repository was skipped, I can inspect which repository it was and what happened. A single total isn't enough when I'm managing thirty checkouts.

Help that works offline

Choosing Help → RepoDeck Help now opens an actual guide instead of macOS's “Help isn't available” dialog. There are 18 searchable topics, with related links and back/forward navigation, covering setup, changes and commits, branches and worktrees, conflicts, hosting reviews, tools, and troubleshooting. Search with ⌘F inside the Help window.

The guide explains recovery limits too. Undo has a specific branch and worktree context; it isn't a backup of every local file. Partial staging has whole-file alternatives when exact content can't be preserved. I want those limits available at the moment I need them, including when the network is down.

Commit authors are different from login credentials

Another confusing message was “No git identity configured.” SSH was working, GitHub showed the right account, and commits could still have an author. The problem was that the footer was looking at configuration defaults rather than asking Git for the effective commit author.

The footer now uses the same Git author lookup an ordinary new commit relies on:

git var GIT_AUTHOR_IDENT

That includes Git's author overrides and the environment inherited by the app. SSH keys prove I can connect to a remote; a GitHub or GitLab login grants hosting access. Neither automatically supplies the name and email recorded in a commit.

Click Configure Author… or Edit Author… in the sidebar to edit the name and email for this repository or the global default, then explicitly save. Repository-specific settings are useful for keeping work and personal addresses separate. The form shows the effective author separately from those editable defaults and explains when an override takes precedence. Failed saves preserve the draft. Existing commits keep their original authors, and the app doesn't replace SSH keys or hosting credentials.

A steadier diff workspace

This release also fixes a reported macOS 27 crash involving the native diff inspector's layout updates. The diff now lives in a split workspace that preserves the current view state as it opens and closes. Repeated open/close cycles were checked locally; the broader keyboard, VoiceOver, and appearance checks remain listed separately in the release verification notes.

Build & Install

Easiest: download RepoDeck.dmg directly (or browse the latest release), open it, and drag RepoDeck onto Applications. When updating, quit the running app before replacing it in Applications. The installer is universal for Apple silicon and Intel, and requires macOS 15 or later.

RepoDeck is ad-hoc signed and not notarized. After verifying the download's SHA-256 against the release checksum and attempting to open it, you may need System Settings → Privacy & Security → Open Anyway. See Apple's first-launch instructions; managed Macs may have additional restrictions. This is the standard distribution — Developer ID signing and notarization are optional future improvements.

From source — Swift 6.2 or newer, Swift Package Manager, no Xcode project needed:

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

Install and authenticate gh or glab only if you want the corresponding hosting integration. 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.2.0: a full code review of the whole repository (about 500 lines of app Swift plus the build and packaging scripts) turned up far more than I expected — a dozen confirmed bugs in the app alone, among them a first-launch default that silently meant Indefinite, a countdown that froze while you were looking at it, and a caffeinate child that outlived the app after a crash. The eight headline bugs are fixed below, Start at Login is rebuilt on SMAppService, the packaging scripts are fixed too, the menu got native checkmarks, an in-menu record of the last session, Activate on Launch and About, and the test suite went from 5 to 87. Details in the v1.2.0 section below. Install with Homebrew — brew install --cask sergio-farfan/tap/nosleep — or download NoSleep-1.2.0.dmg (universal, macOS 14+). The 1.2.0 DMG was rebuilt on 2026-09-12 to include the menu additions; both builds report 1.2.0, so if your menu has no About NoSleep item, download it again (or brew upgrade --cask nosleep).

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 an Extend 1 hour action when a timed session ends (hover the notification to reveal the button; the Alerts style keeps it on screen until you do). The new bits — and the async race the notification introduced — are covered in the v1.1.0 section below.

Features

Homebrew or DMG — brew install --cask sergio-farfan/tap/nosleep, or 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); after a timed session ends, the menu says when
Completion notification — when a timed session ends, a notification offers Extend 1 hour (hover the notification to reveal the button; the Alerts style keeps it on screen until you do)
Start at Login — registers a login item so it auto-starts when you log in (a LaunchAgent plist in ≤ 1.1.0, SMAppService since 1.2.0)
Activate on Launch — optional: start the saved duration the moment NoSleep launches, so login-time protection needs no click
Single instance — launching a second copy exits immediately, and a lock-aware build quits a still-running pre-lock copy (1.1.0, or the 1.2.0 DMG published before 2026-09-12) and its caffeinate, so an upgrade cannot leave two icons
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
Observation (@Observable) — replaced ObservableObject in 1.2.0
ServiceManagement (SMAppService) — Start at Login since 1.2.0
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

Correction (v1.2.0): this section describes NoSleep ≤ 1.1.0. SMAppService does not require a sandboxed app — that was my mistake — and the plist approach below broke silently whenever the bundle moved (the path is baked in at enable time) and reported "enabled" purely from the file's existence. Since 1.2.0 NoSleep uses SMAppService.mainApp, reads the real Background Task Management status, and carries an existing plist's setting over when launched from an installed copy — see Start at Login, done properly below.

NoSleep 1.1.0 wrote 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

v1.2.0: Eight Bugs, a Login Item Rewrite, and 87 Tests

Before this release I ran an automated, multi-agent code review over the whole repository: ten lens-specific reviewers, every bug and medium-severity finding checked by three adversarial verifiers (reproduce / skeptic / impact) and lower-severity items by one, then two further verification passes over the fixes themselves. It found more than I expected in about 500 lines of app Swift plus the scripts around it. The snippets earlier in this article show the 1.1.0 code; here is what changed and why.

The default that was secretly "Indefinite"

let saved = UserDefaults.standard.integer(forKey: "selectedDuration")
self.selectedDuration = SleepDuration(rawValue: saved) ?? .fourHours

Looks fine. But integer(forKey:) returns 0 for a missing key, and 0 is the raw value of .indefinite. So the fallback never ran, and every fresh install started with Indefinite selected — the one preset with no timer and no completion notification. The fix reads the raw object and decides in a pure, unit-tested function:

nonisolated static func restoredDuration(from stored: Int?) -> SleepDuration {
    guard let stored, let saved = SleepDuration(rawValue: stored) else { return .fourHours }
    return saved
}
// in init:  restoredDuration(from: defaults.object(forKey: key) as? Int)

The child that outlived its parent

caffeinate is a child process. If NoSleep crashed, was force-quit, or got killed, macOS did not kill the child — it was reparented to launchd and kept the Mac awake with no UI attached (forever, for Indefinite). caffeinate has a flag for exactly this, and it composes with -t:

var args = ["-d", "-i", "-w", "\(ProcessInfo.processInfo.processIdentifier)"]

-w <pid> releases the assertion and exits as soon as that process is gone.

The countdown that froze while you looked at it

Timer.scheduledTimer registers in the run loop's .default mode. While an NSMenu is open, the main run loop runs in NSEventTrackingRunLoopMode — where .default-mode timers never fire. So the "live countdown" stood still exactly while the menu was open. Worse, each tick decremented a counter, so every second spent looking at the menu went uncounted, and for the rest of the session the display showed more time than actually remained — caffeinate's -t timer expired while the menu still showed minutes left.

Two changes: add the timer in .common mode, and derive the value from a deadline instead of counting down:

let t = Timer(timeInterval: 1, repeats: true) { [weak self] _ in
    MainActor.assumeIsolated { self?.tick() }
}
RunLoop.main.add(t, forMode: .common)

func tick() {
    remainingSeconds = max(0, Int((deadlineUptime - uptime()).rounded(.up)))
    // …
}

The deadline is on ProcessInfo.systemUptime, the same clock family caffeinate -t uses, so both pause together during system sleep. There is a test for this that puts the main run loop into a tracking-style common mode and checks the countdown still moves; reverting to .default fails it.

Two percent CPU for nothing

That 1 Hz tick wrote an @Published property on the app-root @StateObject. Every write fired objectWillChange, which invalidated the whole MenuBarExtra scene, which re-set the status bar button's image, laid it out, committed to WindowServer and re-snapshotted the item for both appearances — about 20 ms of main-thread work per second — the review measured roughly 2 % CPU with the menu closed, for a glyph that had not changed.

Migrating to the Observation framework fixed it with almost no code:

@MainActor @Observable
final class CaffeinateManager {
    var isActive = false
    private(set) var remainingSeconds = 0
    // …
}

// NoSleepApp:  @State private var caffeinateManager = CaffeinateManager()

@Observable tracks which properties each view read. The menu-bar label only reads isActive, so remainingSeconds ticking away no longer touches it. In the same measurement the same tick under @Observable cost about 0.1 %.

The crash outside an .app bundle

UNUserNotificationCenter.current() raises bundleProxyForCurrentProcess is nil and aborts the process unless you are running from a real .app. CaffeinateManager.init() called it — so swift run died instantly, and no unit test could construct the manager. Only the pure notify-decision function had tests; the state machine the whole app depends on had none.

The fix: guard on Bundle.main.bundleURL.pathExtension == "app", and give the manager three injectable seams — a launcher (CaffeinateLaunching), a notification poster (NotificationPosting) and a store (DurationStore). With fakes for all three, the whole start / stop / restart / termination machine runs under swift test without spawning a process or touching UserDefaults.

The stale Extend button

Delivered notifications sit in Notification Center indefinitely. A "Your 2 hours session has ended" banner from the morning still had a live Extend 1 hour button at 4 pm — and tapping it replaced whatever session was running with a one-hour one. Now every stop() (which every restart goes through) clears delivered notifications, and extendOneHour() ignores the action while a session is active.

"Session has ended" — no, it was killed

The termination handler treated every exit the same, so killall caffeinate produced a cheerful completion notification. The launcher now reads the exit reason and only a clean exit counts as expiry:

proc.terminationHandler = { p in
    let clean = p.terminationReason == .exit && p.terminationStatus == 0
    Task { @MainActor in onTermination(clean) }
}

There is also a test that runs the real launcher against /usr/bin/true, /usr/bin/false and a terminate()d sleep, so the mapping itself is covered — not just the code that consumes it.

Start at Login, done properly

The LaunchAgent approach I described above was wrong twice. SMAppService never required a sandbox. And baking Bundle.main.executablePath into a plist meant the login item broke silently the moment the app moved — say, from the mounted DMG to Applications — while the toggle stayed checked because the file still existed.

1.2.0 uses SMAppService.mainApp. The toggle reflects the real Background Task Management status, refreshed every time the menu opens; if the item needs your approval a caption says so, and clicking the toggle takes you to System Settings › Login Items instead of trying to re-register. An existing 1.1.0 plist is migrated when the app is launched from an installed copy. If the old agent was still on, the plist is only deleted once the new registration is actually .enabled — while it awaits your approval the plist stays and a later launch finishes the job. If you had already switched the old agent off under Login Items, the plist is removed without registering anything, so "off" carries over. Either way nobody loses the setting on upgrade. The migration decision is a pure function with its own tests, because the first version of it had a bug the review's second pass caught: it treated "registered, awaiting approval" as "the user turned it off".

Packaging, too

The DMG script assumed its image would mount at /Volumes/NoSleep; with a NoSleep DMG already open it mounted at /Volumes/NoSleep 1 and the script ejected the wrong disk. It now refuses to run while a NoSleep volume is already mounted, reads the device node back from hdiutil attach so it can only ever detach its own image, retries detach while Finder still holds the volume, and ships a multi-resolution TIFF background so Retina displays get the sharp version. The app icon no longer includes 16 and 32 px representations, which current macOS (verified on 27) draws shrunk on a grey plate.

The improvements that rode along

The same review listed a second tier of things that were not bugs but were worth doing. A second pass of the same automated process landed them on 2026-09-12, two days after the first 1.2.0 build, and I rebuilt the 1.2.0 DMG rather than cut a new version — so if you downloaded it before then, download it again. Everything below came from the review except the About box, which I added on my own:

Native checkmarks. The duration presets are real menu toggles, so the selected one gets the system checkmark (and VoiceOver reads it), instead of SF Symbol dots that recent macOS stopped drawing in menus.
The menu remembers. When a timed session runs out, the status line shows an orange dot and "Kept awake for 2 hours — ended 14:32" until you start something new, so a missed notification no longer leaves you guessing. The wording gains the date once it is no longer today's.
Activate on Launch. An opt-in toggle that starts the saved duration as soon as the app launches — the missing half of Start at Login.
About NoSleep. Icon, name, tagline and the installed version, one click away.
Extend keeps your preference. "Extend 1 hour" runs a one-hour session without overwriting the duration you had picked; the checkmark follows the running session and snaps back afterwards.
One instance. A kernel file lock (O_EXLOCK) arbitrates between copies started by open, a login item and launchd within the same millisecond — my first attempt used NSRunningApplication, and the review's probes caught it racing: two copies started together left zero or two instances, because a directly exec'd copy is not registered with LaunchServices until NSApplication initialises and two LaunchServices-launched copies can each see the other and both exit. A lock-aware build also quits a still-running pre-lock build, so upgrading by dragging the DMG over the old app cannot leave two icons.
Notifications. The banner reads "Session ended / Kept your Mac awake for 2 hours. It can sleep again.", stays in Notification Center, and new installs get the persistent Alerts style, so the notification stays on screen until you act (hover it to reveal the Extend button). If you have denied notifications, the menu offers to open the right System Settings pane.
Packaging. The DMG finally ships its volume icon — Finder was deleting the file during the layout step, so it is now applied afterwards — plus Apple's 824-point icon grid, the GPL text inside the bundle, and proper Info.plist metadata.
CI. Every push to main now builds, runs the tests, produces the signed universal bundle, packages and verifies the DMG, and lints the shell scripts on a GitHub-hosted Mac.

Tests: 5 → 87

Every Swift fix above except the Observation migration has a test that fails if the fix is reverted (the packaging changes are shell scripts and assets, outside the test target): the pure decisions, the state machine through fakes, the real launcher's exit mapping, the run-loop-mode test, a deadline-resync test with an injected clock (two ticks inside one second must not double-decrement; one tick after a 65 s stall must jump to the right value), the login-item migration against a scripted fake and a temp plist, the instance lock (exclusivity, stale contents, no leak into the child), the launch hook, the ended-session cue, and the notification text and action routing.

The lesson I am taking from this release: the bugs were not in the clever part (the run-token race from 1.1.0 held up fine). They were in the boring parts — a default value, a run-loop mode, a child process nobody waits for — and none of them were reachable by tests until the class could be constructed outside an .app.

Install: the quickest way is now Homebrew, from my personal tap:

brew install --cask sergio-farfan/tap/nosleep   # first time: accept the prompt to trust the tap
brew upgrade --cask nosleep                      # later updates

Or download NoSleep-1.2.0.dmg — universal (Apple Silicon + Intel), macOS 14+ — open it and drag NoSleep onto Applications. Either way, do the one-time Gatekeeper step in Build & Install below; because releases are ad-hoc signed, macOS asks again after each upgrade. Upgrading from 1.1.0 or from the earlier 1.2.0 build just means replacing the app (Homebrew does it for you); your Start at Login setting is carried over, and the new copy quits the old one.

The tap side is automated too: pushing a version tag builds the DMG, publishes the GitHub Release with a .sha256 sidecar, and fires a repository_dispatch at the tap repository, whose workflow rewrites the cask's version and sha256, re-validates it on a clean runner, and pushes — so brew upgrade sees a new NoSleep within minutes of a release, with no hand-edited formula.

Build & Install

Easiest: Homebrew, from my tap:

brew install --cask sergio-farfan/tap/nosleep

Homebrew 6 and later ask you to trust a third-party tap the first time (brew trust sergio-farfan/tap). Update with brew upgrade --cask nosleep; remove with brew uninstall --cask --zap nosleep.

Or the DMG: download NoSleep-<version>.dmg from the latest release, open it, and drag NoSleep onto Applications.

Either way, on first launch run the xattr command above once (or open it, then System Settings → Privacy & Security → Open Anyway); ad-hoc signed builds get a new code identity per release, so expect that step again after each upgrade until I notarize.

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 (full Xcode for swift test), 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.

One Option-Tab: every open window, most-recent first, on the screen where your mouse is.

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.3

Glass Strength. Liquid Glass now has four levels — Light / Medium / High / Max — in the status menu (macOS 26+). NSGlassEffectView exposes no intensity control, so the levels are emulated: High is the original regular glass; Light and Medium lay an appearance-adaptive translucent plate over it, calming the effect toward the Solid look; Max switches to Apple's clear glass style, the most see-through. Takes effect on the next Option-Tab.
Homebrew. brew install --cask sergio-farfan/tap/alttab — and the release pipeline now bumps the cask itself, so brew upgrade --cask alttab tracks every release.
First-launch guidance for the unsigned build follows Apple's current flow (System Settings → Privacy & Security → Open Anyway).

What's New in 1.3.2

1.3.1 fixed which slot the first Tab lands on; 1.3.2 makes sure the list itself is never stale — and makes the slow paths fast:

The window list stays warm. The list used to be re-gathered only while the switcher was open, so the first Option-Tab after a long idle opened from a snapshot frozen at your previous session. Now every focus change, app activation, launch, and termination schedules a debounced background refresh — rate-limited, so sustained window-hopping costs one sweep per 8 seconds, not one per switch.
A busy app can't corrupt the order. A single 0.25s Accessibility timeout from a wedged or App-Napped app used to silently drop its minimized and other-Space windows from the list and permanently demote their MRU ranks. Windows of apps that fail to answer are now carried over from the previous gather, ranks intact.
Option-Shift-Tab opens the switcher backward. Just like Windows: the initial reverse invoke anchors on the least-recently-used window and keeps cycling backward from there.
Faster everywhere it was slow. The per-app Accessibility pass now runs concurrently instead of stacking per-app timeouts sequentially; raising or unminimizing a window of a wedged app is bounded by per-window timeouts (previously up to ~6s per call); the focused-window probe moved off the main thread so a slow app can't stall the event tap; app icons resolve off the main thread too.
The pure-logic core is now five unit-tested types (SwitcherSelection, MRUOrder, SwitcherStateMachine, GatherMerge, Debouncer) — 83 tests.

What's New in 1.3.1

This release is entirely about the first Option-Tab. The bug report that started it: after the switcher had sat idle for a while, a single Tab would sometimes land two or three windows back instead of on the window you had just left. An adversarially verified code review traced it to five root causes. All five are fixed, and the selection logic that decides which slot the first Tab lands on is now a pure, unit-tested type.

The first Tab lands on the previous window — every time. The panel opens from a cached window list re-sorted by live MRU order, so a window you had opened (or closed) since the last gather was missing from (or lingering in) the list, shifting every slot by one. The initial highlight is now anchored against the window that actually has focus, and the mid-session reconcile re-anchors against the fresh list unless you have already cycled or clicked.
Background apps can no longer scramble the order. kAXFocusedWindowChanged fires for non-frontmost apps too — Electron/Chromium window churn, a Terminal window closing when its job finishes — and each event used to silently jump to the front of the MRU while you worked elsewhere. Only the frontmost app's focus changes count now.
No more phantom switches. Confirming a window that had been closed since the last gather used to fall through to "raise the app's first window" — an arbitrary one. Confirm now verifies liveness with one batched WindowServer query and falls through to the next real window; the arbitrary-raise fallback is gone.
Intra-app tracking survives updates. Every release re-prompts for Accessibility (ad-hoc signing), and the per-app AX observers were registered before the grant — the failures were stored as if they had succeeded, so Cmd-` switches went untracked for the whole session. Observers now register only on success, reinstall the moment the grant arrives, retry for just-launched apps, and self-heal on an app's first activation.
Rapid toggling is stable. Option-Tab-ing straight back after a switch treats the in-flight activation as focus ground truth, so a quick flick can't anchor on the window you just switched to and turn into a no-op.

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 macOS blocks the first launch: open System Settings → Privacy & Security, click Open Anyway, then launch again (or clear the quarantine flag):

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

Homebrew

brew install --cask sergio-farfan/tap/alttab

The fully qualified name trusts just this cask (Homebrew 6+ requires third-party taps to be trusted). For short names, brew trust sergio-farfan/tap && brew tap sergio-farfan/tap first. Updates: brew upgrade --cask alttab. The same first-launch Open Anyway step applies.

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 (90)

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-`) — accepted only from the frontmost app, because background apps fire focus-changed notifications too. Explicit activations are pinned so the asynchronous window-raise can't demote the window you just picked, and the pin is superseded the moment a different app or window takes focus.

Focus-anchored selection — The list you see is served from a cache and can be one gather stale, so the switcher never assumes slot 0 is the window you are on. At open it determines which window really has focus (a fresh in-flight activation if there is one; otherwise the frontmost app's topmost window via a single WindowServer query, escalating to one bounded Accessibility call only when that window is unknown to the cache) and highlights the first window that isn't it. Confirm walks the same order past any window that no longer exists. The whole policy — anchor, cycle, reconcile, confirmation order — lives in a pure SwitcherSelection type with a test table for every stale-cache shape.

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.

Three More, from 1.3.1

[CGWindowID] as CFArray silently matches nothing. CGWindowListCreateDescriptionFromArray takes a CFArray of window IDs — and the natural Swift bridge, ids as CFArray, compiles, runs, and returns an empty array for every live window. The function wants the IDs stored directly as pointer-sized values with NULL callbacks, not as CFNumbers. My first liveness check did exactly the wrong thing, which would have turned every confirm into a no-op. A ten-line probe against two real window IDs plus one bogus one caught it before it shipped (and four independent review passes flagged it too). The working form:

var values: [UnsafeRawPointer?] = ids.map { UnsafeRawPointer(bitPattern: UInt($0)) }
let array = CFArrayCreate(kCFAllocatorDefault, &values, values.count, nil)

kAXFocusedWindowChanged does not mean "the user focused a window". It means "this app's focused window changed" — and it fires for apps in the background. Chromium- and Electron-based apps churn windows while idle; a Terminal window closing when its job exits moves focus to a sibling. Each event, taken at face value, is a counterfeit "most recently used" entry. Check the element's pid against NSWorkspace.shared.frontmostApplication before you believe it (AXUIElementGetPid reads the pid out of the element token — no IPC).

AXObserverAddNotification returns an error you must read. Before Accessibility is granted it fails with kAXErrorAPIDisabled; right after an app launches it can fail because the app's AX server isn't accepting registrations yet. If you store the observer anyway — and gate "already installed" on that dictionary — the app stays silently unobserved until you relaunch. Since ad-hoc signing re-prompts for Accessibility on every release, that made the first session after every update the broken one. Store on .success only, reinstall when the grant arrives, and let an app's first activation heal anything that slipped through.

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,800 lines of Swift across 17 source files, plus a unit-tested core (90 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 (Sep 2026): v1.5.0 is out — one diagram model, many views. Six purpose presets — network topology, application / data flow, security, inventory, dependency and high availability — compose detail levels, label modes, draw.io layers and filters behind a single flag, and the new network label mode renders a resource’s name, private IP and ports from the model’s metadata. Routes, security, IAM and the connector kinds can be emitted as real draw.io layers on request, and filtering by tag, compartment, VCN, subnet, resource type and environment — plus a participating mode that draws only what takes part in the architecture and an optional tenancy-scoped global-services bucket — keeps a large tenancy readable. See "What's new in v1.5.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 a dozen categories and 150+ 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 a Terraform directory, a terraform show -json plan or state file, a VCN name resolved against your .tfvars, or a plain-text description of the target architecture. An experimental mode can also read a live tenancy through the OCI CLI topology API.

From any of these inputs it builds a small model of the architecture — VCNs, subnets with their tier, the resources in each subnet, regional services, gateways, the on-premises side and the connections — and hands it to a deterministic layout recipe. The recipe places subnets in traffic order, puts the OCI Services panel beside them, stretches the data tier underneath, lines up the gateways, centres the hub on the VCN, and routes every connector through the gutters so lines never cross an icon or a caption. The result is a .drawio file styled with Oracle's Redwood palette backed by 159 bundled OCI SVG icons, validated for overlaps, containment and collisions before it is written, and rendered to PNG when draw.io desktop is installed.

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+ (standard library only)
draw.io desktop for viewing generated .drawio files and for the PNG export

Pillow is optional and only needed to embed PNG logos; SVG logos need nothing.

Installation

Step 1 - Download, Extract and Install

One command:

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

This will:

Download, extract and execute the installer script
Check prerequisites (Python 3; tries to install Pillow, but continues without it)
Create or update the local marketplace at ~/.claude/plugins/marketplaces/local/ (other plugins in it are preserved)
Copy the plugin files into the marketplace
Verify all components (8 checks, including a smoke test that builds and validates a demo diagram)

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.5.0

v1.4.0 settled where a thing goes; v1.5.0 answers what goes in, and how much of it — one discovered topology, several readable views. The controls implement the team's diagram guidelines — the sections on filters, connector semantics, label modes and layers — and reviewer feedback that a full-detail hybrid diagram is unreadable as a management artefact.

One Terraform stack, six diagrams. --purpose names the view — network topology, application / data flow, security architecture, resource / inventory, dependency / relationship, deployment / high availability — the six the guidelines list. Each composes a detail level, a label mode, a layer set and a mode; any explicit flag still beats the preset.

An executive-to-engineering detail ladder. --detail executive|application|network|engineering gates content and sets the rest of the view's defaults. network is today's output; executive drops the badges, the CIDRs and the connector labels and reduces captions to names; engineering shows everything. One model, both the one-page overview and the engineering drawing.

Captions are a rendered field list. --label-mode minimal|network|detailed follows the guidelines' label-mode table over a documented vocabulary: name, type, private and public IP, CIDR, FQDN, port / protocol, compartment, AD / FD, lifecycle and tags. An OCID is never rendered in a caption, in any mode.

Layers you toggle in draw.io. With --layers auto, route, security, IAM, data-flow, management and association content goes onto real draw.io layers above a base layer named Network, switched in the layer panel (Cmd/Ctrl+Shift+L) without regenerating the file. The pass only re-parents cells, so enabling it cannot move a pixel.

Filters for large tenancies. One predicate over tags, compartment, region, VCN, subnet, resource type, environment and application, applied identically by the parser, the live-tenancy reader and the layout CLI. --mode participating draws only what takes part in the architecture — the live-tenancy default; Terraform stays on all — and --global-services bucket moves IAM, Policies, Audit and public DNS into a tenancy-scoped box below the region.

What changes if you change nothing is the caption of a parsed model: the shape line moves into the metadata, and a private IP and a port list appear when the input has them. A hand-written label is untouched, --label-mode minimal --label-fields display_name,shape brings the 1.4 caption back exactly, the geometry is identical, and the schema stays at 2.

One caveat: a purpose's hidden layers only take effect with --layers auto (or an explicit list). Layers are off by default, and with them off a "hidden" layer's content is simply not drawn rather than emitted and hidden.

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

What's new in v1.4.0

v1.3.0 made placement topology-aware inside the region box; v1.4.0 takes it outside. Everything here is about where a thing goes, and the rules come from Oracle's Architecture Diagram Toolkit deck and its published reference architectures, read alongside the team's diagram guidelines and reviewer feedback.

The location boxes leave the region. On-Premises, Internet and 3rd Party Cloud are page-level siblings of the OCI Region — On-Premises left, Internet and 3rd Party stacked right — the arrangement Oracle's Location Canvas defines. The Site-to-Site VPN / FastConnect / Remote Peering label sits in the gap between the on-premises box and the region, and a CPE or virtual circuit straddles that box's region-facing border the way a gateway straddles a VCN border. For a hybrid architecture the whole chain — CPE, hybrid link, attachment, DRG, VCN — now reads across the page.

Gateways face what they connect to. The Internet Gateway and the NAT Gateway take the VCN border facing the Internet box: the right border for the rightmost VCN column, the top border with captions above the glyphs for every other column, since a left-hand column's right border faces the next VCN. Each Internet Gateway gets an attachment connector to the Internet box, mirroring the Service Gateway's to the Oracle Services Network. Within a border the order is always IGW, NAT, Service Gateway, LPG — never model order.

The Oracle Services Network is a band below the VCN stack, fed by the Service Gateway on the VCN's bottom border — the right-hand column is where the Internet box went, and a services panel there would have every Internet-bound connector crossing it.

Compartments and grouping boxes become drawable. A compartment can wrap the VCNs it holds, nested, with an optional tenancy wrapper — opt-in, because a view with every compartment drawn is unreadable. Grouping boxes cover an OKE cluster inside a subnet (the Terraform parser emits one when a cluster and its node pools share a subnet) plus Oracle's tier and user-group boxes. A box is a real container: members are re-parented into it, the router avoids it, and a connector may terminate on it.

Smaller things: the DRG carries up to two route-table badges — the pair Oracle creates by default — subnet labels are two lines with a (Public) / (Private) token, the legend gains a row per badge kind drawn, and the attachment connector can be solid or dotted.

The old canvas is one flag away: --locations nested restores the 1.3.x layout exactly. Five new flags on oci_layout.py — --locations, --gateway-edge, --subnet-label, --attachment-style and --show-compartments — have matching model keys. The schema stays at 2, new keys are optional, and a 1.3.x model renders unchanged apart from the two default flips.

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

What's new in v1.3.0

v1.2.0 made the layout deterministic; v1.3.0 makes it topology-aware, which matters most if what you document is hub-and-spoke or hybrid. The placement rules come from Oracle's Architecture Diagram Toolkit deck and Oracle's published reference architectures, read alongside the team's diagram guidelines and reviewer feedback on what the plugin was producing.

The DRG is regional connectivity infrastructure, so it is drawn outside every VCN, centred on the VCN stack, with one labelled box per attachment beside it — VCN attachments facing the VCNs, Site-to-Site VPN, FastConnect and Remote Peering attachments facing the on-premises side. Before, the DRG arrived as an item in the on-premises panel or as a gateway icon inside the VCN; now the chain VCN — attachment — DRG — remote network is explicit on the canvas.

Gateways sit on the VCN border. Internet and NAT gateways straddle the bottom edge, the Service Gateway the right edge facing the services, and a Local Peering Gateway the edge facing its peer VCN.

Regional services share one Oracle Services Network panel. Logging, Vault, Notifications, IAM, Object Storage, Generative AI and the like are region-level rather than VCN-resident, so they are drawn once, right of the VCN columns, and reached through the Service Gateway.

Connector style carries meaning: a solid arrow is application or data flow, a dashed arrow is management traffic, a dotted line is an association or dependency, and a plain line without an arrowhead is a structural attachment. The legend names all four.

Route tables, security lists and NSGs are badges, not icons. A subnet carries its route table and security lists as small badges on its top-right corner, and an NSG is a shield on the resource it protects, with the names in the tooltip.

A classifier picks the presentation from the model — single VCN, multi-VCN, VCN with a DRG, hub-and-spoke, hybrid — and --drg-style icon|box overrides it. The validator refuses a DRG drawn inside a VCN, and any icon sitting in a VCN or subnet it does not belong to. Models written for 1.2.0 still build; they are migrated to schema 2 with a warning.

One thing v1.3.0 deliberately does not do is use draw.io's MCP connector: draw.io's built-in shape libraries carry no OCI icons, local generation keeps diagram content — VCN names, CIDRs, OCIDs — on your machine, and the connector's inline preview needs an MCP Apps host, which Claude Code is not.

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

What's new in v1.2.0

v1.1.0 fixed rendering fidelity; v1.2.0 fixes consistency. I went back to the diagram I had published as the reference and asked why newly generated diagrams kept drifting from it. The answer was a mix of tooling bugs and under-specified instructions, and v1.2.0 addresses both.

Diagrams are data now. Instead of asking Claude to compute coordinates, the command fills in a model dict — subnets with a tier, the icons in each, the services panel, the gateways, the hub, the edges — and oci_layout.py lays it out with the same recipe every time. The reference diagram itself is now just a model (examples/generate_reference_layout.py), and it rebuilds pixel-for-pixel in the same structure.

import sys
sys.path.insert(0, "/path/to/oci-drawio-architect/scripts")
from oci_layout import write_diagram

MODEL = {
    "subject": "app-prod", "region": "eu-frankfurt-1", "region_label": "Frankfurt",
    "vcns": [{"name": "app-vcn", "cidr": "10.0.0.0/16", "subnets": [
        {"name": "sn-lb", "cidr": "10.0.0.0/24", "tier": "lb",
         "items": [{"icon": "load_balancer", "label": "Load Balancer\n10.0.0.7", "address": "lb"}]},
        {"name": "sn-app", "cidr": "10.0.1.0/24", "tier": "app",
         "items": [{"icon": "vm", "label": "App VM\n10.0.1.5\n4 OCPU / 32 GB", "address": "app"}]},
        {"name": "sn-db", "cidr": "10.0.2.0/24", "tier": "data",
         "items": [{"icon": "autonomous_db", "label": "ADB prod\napp-db", "address": "adb"}]}],
        "gateways": [{"icon": "service_gateway", "label": "Service\nGateway", "address": "sgw"}]}],
    "edges": [{"source": "lb", "target": "app", "label": "8080", "kind": "data"},
              {"source": "app", "target": "adb", "label": "1522", "kind": "data"}],
}
write_diagram(MODEL, "app-prod_Architecture.drawio", render_fmt="png")

Terraform in, model out. parse_terraform.py reads HCL (with var. and local. resolution, cidrsubnet() included) or terraform show -json plan and state files and produces that model, so count, for_each and computed CIDRs are handled by Terraform rather than by regexes. An experimental query_tenancy.py does the same from a live tenancy via oci network vcn-topology get.

Connectors that route themselves. v1.1.0 handed edges to draw.io's orthogonal router, which does not avoid anything. v1.2.0 routes each connector on a lattice of container margins and gutters, penalising icons, captions, container titles and foreign containers, spreading parallel edges across corridors and placing labels where they collide with nothing. On the reference diagram the estimated crossings went from six (my hand-routed original) to zero. route="direct" and pinned ports are still there when you want them.

Icons finally look alike. Sixteen of the most common icons — VM, Functions, Block Volume, Object Storage among them — carried a leftover caption-placeholder rectangle from the original stencil conversion. It drew a faint box under the glyph and made those glyphs about a third smaller than their neighbours. The rectangle is gone, every viewBox is cropped to the glyph, and each glyph is fitted into the same 70×70 box. Fifty-five empty stencil shells that rendered as invisible cells were removed; the set is now 159 real icons, every one addressable by its file name or one of 206 short aliases.

The look you expect, with an official escape hatch. Region and compartment labels are back at the top-left, the services panel is charcoal again, dashed connectors have a proper dash pattern, and every style carries a font stack so machines without Oracle Sans get a sans-serif face instead of Times. Three profiles: default (the reference look with Oracle's 12 px labels), official (strict toolkit values: 1 pt sharp connectors, open arrowheads) and v1.0 (byte-for-byte the old sample).

A validator instead of an overlap checker. check_overlaps.py now reports overlaps between any two containers, shapes that leave their parent, icon and caption collisions, unknown parent or endpoint ids (which used to make draw.io silently drop the whole diagram), captions that need more lines than they have, and estimated edge crossings. Exit 0 means clean; --strict makes crossings blocking. render_drawio.py exports a PNG through draw.io desktop so the command can look at its own output before reporting.

Bugs you might have hit. Copying drawio_builder.py into a project, as the old docs said to do, broke icon lookup — the builder now finds its icons from the plugin location and the docs say to import instead. region = var.region is resolved. eu-london-1 never existed; London is uk-london-1. The installer no longer dies when pip is missing, no longer rewrites other plugins' marketplace entries, and falls back to cp when rsync is absent. The settings file is really gitignored now.

Also: legends, HTML rule tables, multi-page files, deterministic cell ids (key=), metadata/tooltips/links, a reproducible pack.sh, an Oracle attribution notice for the icons, and 954 unit tests.

Compatibility

v1.0 and v1.1 scripts keep running: check_overlaps(), pinned ports, waypoints and the hub alias are all preserved, and write() now also accepts plain strings. Regenerated diagrams will look different — uniform icons, left-aligned location labels, routed edges — which is the point. The one thing to change is the import: point sys.path at the plugin's scripts/ directory instead of copying the builder.

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

What's new in v1.1.0 (July 2026)

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 owns the whole job

Watching the Filesystem Without Hammering It

Map the repository before filtering the path

A 300ms debounce — no timer hammering your disk

The Truncation Seam

From Dashboard to Git Client

History, branches, and worktrees

Conflicts and code review

The safety work behind the buttons

Making Errors Useful

Help that works offline

Commit authors are different from login credentials

A steadier diff workspace

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

v1.2.0: Eight Bugs, a Login Item Rewrite, and 87 Tests

The default that was secretly "Indefinite"

The child that outlived its parent

The countdown that froze while you looked at it

Two percent CPU for nothing

The crash outside an .app bundle

The stale Extend button

"Session has ended" — no, it was killed

Start at Login, done properly

Packaging, too

The improvements that rode along

Tests: 5 → 87

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.3

What's New in 1.3.2

What's New in 1.3.1

What's New in 1.3

What's New in 1.2

Installation

Download (recommended)

Homebrew

Build from source

Permissions

How It Works

Two More macOS Gotchas

Three More, from 1.3.1

When the Accessibility Toggle Lies

Project Stats

Try It Out

Generate OCI Architecture Diagrams from Terraform with One Claude Code Command

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

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore