DEV Community: Sergio Farfan Cardenete

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.

Features

Multi-repo dashboard — track any set of folders; RepoDeck recursively discovers every git repo underneath them
Live status via FSEvents — no polling, no timers; the sidebar badge updates the moment a file changes on disk
Stage, commit, and sync — pull, push, and fetch per repo, plus Fetch All / Pull All across every tracked repo at once
History search by commit message, author, file path, or content (git's pickaxe search)
Sidebar filter and pinning for the repos you touch most often
Themes — System/Light/Dark, custom accent color, fonts, and font size (⌘,)
Resizable Changes/History split, so you can give more room to whichever pane you're using

The Stack

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

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

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

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

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

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

The XY fan-out

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

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

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

Renames consume the next token

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

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

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

Untracked files and merge conflicts

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

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

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

ProcessRunner: One Subprocess Primitive for Everything

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

The pipe-drain deadlock

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

async let stderrData = drainAll(stderrStream)

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

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

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore

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

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

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

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

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

Cancellation kills the child, not just the `Task`

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

} onCancel: {
    kill(pid, SIGTERM)
}

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

Watching the Filesystem Without Hammering It

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

Ignoring `index.lock` churn

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

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

A 300ms debounce — no timer hammering your disk

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

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

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

The Truncation Seam

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

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

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

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

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

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

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

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

var client = GitClient()
client.statusOutputLimit = 64

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

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

Build & Install

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

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

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

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

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

Source Code

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

Built with Swift 6 and SwiftUI on macOS.

NoSleep: Prevent your Mac to go sleep. Period.

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

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

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

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

Features

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

The Stack

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

App Entry Point: MenuBarExtra

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

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

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

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

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

Core Logic: CaffeinateManager

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

Spawning the Process

func start() {
    stop()

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

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

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

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

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

A few things worth noting:

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

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

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

Duration Options

Durations are a typed enum with raw values in seconds:

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

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

Login Item: LaunchAgent Plist

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

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

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

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

Pick a duration → it just starts

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

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

A completion notification you can act on

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

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

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

The stale-termination trap

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

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

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

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

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

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

Download-and-run distribution

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

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

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

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

Build & Install

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

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

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

# Run
open NoSleep.app

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

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

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

Source Code

NoSleep is open source under the GPLv3.

GitHub: github.com/sergio-farfan/nosleep

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

Built with Swift 6 and SwiftUI on macOS Sonoma.

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

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

What It Does

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

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

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

What's New in 1.3

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

What's New in 1.2

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

Installation

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

Download (recommended)

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

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

Build from source

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

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

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

Permissions

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

How It Works

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

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

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

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

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

Two More macOS Gotchas

The 1.3 work surfaced two API behaviors worth knowing about.

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

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

When the Accessibility Toggle Lies

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

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

tccutil reset Accessibility <bundle-id>

then relaunch and grant again.

Project Stats

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

Try It Out

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

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

Feedback, issues, and PRs are welcome!

Generate OCI Architecture Diagrams from Terraform with One Claude Code Command

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

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

The problem

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

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

Diagrams drift from reality

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

The OCI icon set is not native to draw.io

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

Layout is time-consuming

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

Hub-and-spoke topologies are especially difficult

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

Diagrams are created once and abandoned

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

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

What I built

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

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

How it works

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

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

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

Step by Step Installation

Prerequisites

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

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

Installation

Step 1 - Download, Extract and Install

One command:

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

This will:

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

Step 2 - Register in Claude Code

Open Claude Code and run these two commands:

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

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

Step 3 - Verify

Run inside Claude Code:

/drawio-architect

The command should prompt you for what to diagram.

Example Snippet:

What's new in v1.1.0

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

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

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

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

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

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

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

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

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

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

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

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

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

Python 3.9 is now the floor (was 3.8).

Compatibility

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

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

DEV Community: Sergio Farfan Cardenete

RepoDeck: a native macOS dashboard for all your git repos

Features

The Stack

Parsing git status --porcelain=v2 -z

The XY fan-out

Renames consume the next token

Untracked files and merge conflicts

ProcessRunner: One Subprocess Primitive for Everything

The pipe-drain deadlock

GIT_TERMINAL_PROMPT=0 and a 6-slot semaphore

Cancellation kills the child, not just the Task

Watching the Filesystem Without Hammering It

Ignoring index.lock churn

A 300ms debounce — no timer hammering your disk

The Truncation Seam

Build & Install

Source Code

NoSleep: Prevent your Mac to go sleep. Period.

Features

The Stack

App Entry Point: MenuBarExtra

Core Logic: CaffeinateManager

Spawning the Process

Duration Options

Login Item: LaunchAgent Plist

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

Pick a duration → it just starts

A completion notification you can act on

The stale-termination trap

Download-and-run distribution

Build & Install

Source Code

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

What It Does

What's New in 1.3

What's New in 1.2

Installation

Download (recommended)

Build from source

Permissions

How It Works

Two More macOS Gotchas

When the Accessibility Toggle Lies

Project Stats

Try It Out

Generate OCI Architecture Diagrams from Terraform with One Claude Code Command

The problem

Diagrams drift from reality

The OCI icon set is not native to draw.io

Layout is time-consuming

Hub-and-spoke topologies are especially difficult

Diagrams are created once and abandoned

What I built

How it works

Step by Step Installation

Prerequisites

Installation

Step 1 - Download, Extract and Install

Step 2 - Register in Claude Code

Step 3 - Verify

What's new in v1.1.0

Compatibility

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

`GIT_TERMINAL_PROMPT=0` and a 6-slot semaphore

Cancellation kills the child, not just the `Task`

Ignoring `index.lock` churn