8000 GitHub - hongmono/Lathe: Fan-shaped ⌘+Tab replacement for macOS · GitHub
[go: up one dir, main page]

Skip to content
hongmonoPublic

About

Fan-shaped ⌘+Tab replacement for macOS

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Lathe

A safer, self-built ⌘+Tab replacement for macOS.

Why • Install • Build • Use • Preferences • Permissions • Tech • License

English · 한국어


Lathe takes over the system ⌘+Tab and shows a fan-shaped carousel of your running apps, with apps visible in the current Space listed first. The card at the top is always the focused app — hold ⌘ and tap Tab to rotate the deck, release ⌘ to switch.

The app UI is localized in English and Korean, following the system language preference.

Lathe carousel

Why

I wanted ⌘+Tab to look more interesting than a row of icons, and I wanted to be able to read the source of whatever was intercepting my keystrokes. Lathe is the result — small enough to audit in an afternoon, signed by your own identity, no third-party permissions to worry about.

Install

Three paths:

  • Build it yourself (recommended — that's the point of this project; see Build from source)

  • Homebrew:

    brew install hongmono/tap/lathe
  • Download a signed build from Releases — the release DMG is signed with the maintainer's Developer ID certificate and notarized by Apple. Open the DMG, move Lathe.app to Applications, then launch it normally.

Build it yourself

  1. Install the build dependency:

    brew install xcodegen
  2. Clone, generate the Xcode project, and open it:

    git clone https://github.com/hongmono/Lathe.git
    cd Lathe
    xcodegen generate
    open Lathe.xcodeproj
  3. In Xcode, select the Lathe target → Signing & Capabilities → Team: your signing identity (see Code signing below). Run with ⌘R.

  4. The first launch opens Preferences > Permissions if Accessibility is missing. Grant Accessibility in System Settings, then quit and run again — event taps need a fresh process to attach.

That's it. There is no DMG, no notarization, no xattr workaround. The whole binary lives in your DerivedData and is signed with your local identity.

Build from source

Toolchain

Tool Version
macOS 14.6 (Sonoma) or later
Xcode 15+ (project tested on Xcode 26)
Swift 6.0
xcodegen latest (brew install xcodegen)

Code signing

Lathe is signed with a self-signed Code Signing certificate named Lathe Local Dev, stored in your login keychain. This matters because macOS's TCC (the privacy database that grants Accessibility) tracks apps by signing identity — using a stable identity means granted permissions persist across rebuilds instead of being revoked every time the cdhash changes.

To create the certificate:

  1. Open Keychain Access → menu Certificate Assistant → Create a Certificate…

  2. Set:

    • Name: Lathe Local Dev
    • Identity Type: Self Signed Root
    • Certificate Type: Code Signing
  3. Check "Let me override defaults", click Next through the wizard, and bump Validity Period to 3650 (10 years) so it doesn't expire on you.

  4. Finish.

  5. Authorize the new key for codesigning:

    security set-key-partition-list \
      -S apple-tool:,apple:,codesign: -s \
      -D "Lathe Local Dev" -t private \
      ~/Library/Keychains/login.keychain-db

    When prompted, enter your macOS login password.

If you'd rather use a different identity (your own Developer ID, a team certificate, etc.), override the signing build settings locally:

# Project.yml
settings:
  base:
    CODE_SIGN_IDENTITY: "Your Identity Name"
    DEVELOPMENT_TEAM: "YOUR_TEAM_ID"   # or "" for self-signed
xcodebuild -project Lathe.xcodeproj -scheme Lathe \
  CODE_SIGN_IDENTITY="Your Identity Name" \
  DEVELOPMENT_TEAM="YOUR_TEAM_ID" \
  build

Day-to-day

Anytime Project.yml or a Swift source changes, regenerate the Xcode project:

xcodegen generate

Then build/run from Xcode (⌘R), or from the command line:

xcodebuild -project Lathe.xcodeproj -scheme Lathe -configuration Debug build
xcodebuild -project Lathe.xcodeproj -scheme Lathe test

Use

Input Effect
⌘+Tab Open carousel, focus the previous app
⌘ held + Tab Rotate forward
⌘ held + ⇧Tab Rotate backward
⌘ released Activate the focused (center) app (and window)
⌘ held + Esc or . Dismiss without switching
⌘ held + H Hide or reveal the focused app without switching
⌘ held + Q Ask the focused app to quit without switching
⌘+` Cycle windows, or browser tabs when enabled
⌘ held + ⇧` Cycle backward

Behavior matches the system ⌘+Tab so the muscle memory still works — the only difference is that the focus is fixed at the top of the carousel and the cards rotate around it.

Per-window switching. When the focused app has more than one window, a window list appears above the carousel. ⌘+ (the same key macOS uses to move between an app's windows) cycles through them; ⇧ reverses the direction. Pressing ⌘+ on its own — without opening the carousel first — jumps straight into the frontmost app's windows. Releasing ⌘ raises just the selected window, without pulling its sibling windows forward. Windows are ordered most-recently-used, and document/URL windows show a shortened path next to the title.

Browser-tab switching. Enable Preferences → Carousel → Show browser tabs with ⌘` to cycle tabs instead of windows in supported browsers. Lathe groups tabs by browser window and activates the selected tab when you release ⌘. Safari, Chrome, Brave, Edge, Vivaldi, Firefox, Arc, and Aside are supported when they expose pressable tab controls through Accessibility. If a browser does not expose its tabs, Lathe automatically keeps using the regular window list.

Preferences

Open from the Lathe menu bar icon → Preferences….

Lathe preferences window

Section Setting What it does
Appearance Language System / English / Korean
Appearance Theme System / Light / Dark
Carousel Card size Card width; height & pivot scale with it
Carousel Spacing Angle (degrees) between adjacent cards
Carousel Show app names Toggle labels inside carousel cards
Carousel Show browser tabs with ⌘` Use tabs instead of windows when available
Hidden Apps App toggles Hide selected apps from the carousel
General Launch Lathe at login Register as a Login Item via SMAppService

The carousel sliders update live — leave the Preferences window open, hit ⌘+Tab, and tweak.

Permissions

Lathe needs Accessibility permission to install the CGEventTap that intercepts ⌘+Tab globally. There is no other permission requested — no Input Monitoring, no Full Disk Access, no Screen Recording. The event tap is scoped to keyDown for ⌘ + Tab/⇧Tab /`/Esc only; everything else passes through unmodified. The optional browser-tab switcher uses the same Accessibility permission; it does not request browser-specific Automation access.

If you ever want to revoke: System Settings → Privacy & Security → Accessibility → toggle Lathe off (or remove it entirely).

The TCC entry survives rebuilds because the app is signed with a stable identity. If you change the signing identity (or rotate the certificate), you'll be prompted once more and can clear the old record with:

tccutil reset Accessibility com.hongmono.Lathe

Tech

  • SwiftUI + AppKit hybrid. The carousel is a SwiftUI view hosted inside an NSPanel overlay; the menu bar item, hot key tap, and workspace observers are AppKit.
  • Fan layout. Each card is rotated around an off-frame pivot via rotationEffect(_:anchor:). The center card has angle 0; neighbors spread out by ±n × angularStep. No manual trig, no GeometryReader gymnastics.
  • Event tap. Two CGEventTap instances on cgSessionEventTap / headInsertEventTap — one for flagsChanged (track ⌘ press/release), one for keyDown (intercept Tab / ⇧Tab / ` / Esc and consume them).
  • App list. NSWorkspace.runningApplications filtered to .regular activation policy, ordered by an in-process MRU queue fed by didActivateApplication notifications.
  • Window list. Per app, WindowListProvider reconciles the Accessibility window list against CGWindowListCopyWindowInfo (matching by window id, title, then frame), filters out non-user windows, and orders the result most-recently-used. Titles pick up a short document/URL path summary when the window exposes one.
  • Browser tabs. When enabled, AccessibilityBrowserTabProvider discovers pressable browser tab controls in each window, preserves their window grouping, and selects the chosen tab through Accessibility. An empty or unsupported tab hierarchy falls back to the normal window list.
  • Single-window raise. Selecting a window raises only that window via SkyLight (_SLPSSetFrontProcessWithOptions) instead of activating the whole app — the same approach AltTab and yabai use — so sibling windows stay where they are.
  • Settings store. ObservableObject backed by UserDefaults, observed by the overlay so geometry changes apply live.
  • Private API is opt-in and fenced. The carousel and app switching use only public, documented API. The per-window features additionally rely on two private symbols — _AXUIElementGetWindow (to map an AX window to its CoreGraphics window id) and SkyLight's front-process calls (to raise a single window). Both are resolved at runtime via dlsym; if either is unavailable the code falls back to the public Accessibility path (kAXMainAttribute + kAXRaiseAction) and normal app activation, so nothing breaks if Apple removes them.

Project layout

Lathe/
├── App/            LatheApp.swift, AppDelegate.swift
├── HotKey/         HotKeyMonitor.swift          (CGEventTap, key actions)
├── AppList/        AppEntry.swift, AppListProvider.swift,
│                   WindowEntry, WindowListProvider, BrowserTabProvider,
│                   WindowVisibilityFilter,
│                   WindowOrderTracker, WindowFocusTracker, WindowPathSummary
├── Overlay/        OverlayPanel + Controller, OverlayRootView,
│                   CarouselViewModel/Layout, CardView,
│                   WindowListView, WindowSelectionViewModel
├── Activation/     AppActivator.swift, SingleWindowFocuser.swift (SkyLight)
├── Permissions/    AccessibilityChecker
├── MenuBar/        MenuBarController.swift
├── Settings/       SettingsStore, SettingsView, SettingsWindowController,
│                   Appearance, LoginItem
└── Resources/      Info.plist, Assets.xcassets
LatheTests/         CarouselViewModelTests, HotKeyActionTests,
                    AppEntryFilteringTests, WindowListProviderTests,
                    WindowOrderTrackerTests, WindowPathSummaryTests,
                    WindowSelectionViewModelTests
docs/
├── superpowers/    specs/  plans/                (design history)
└── images/         README screenshots

Spec & plan

The original design spec and implementation plan are checked in:

Releases

A GitHub Actions workflow at .github/workflows/release.yml builds a signed Release archive whenever the release branch receives a push. It reads the release version from VERSION, packages Lathe.app into a DMG, notarizes and staples the DMG, creates the matching v* tag, then attaches the DMG and Sparkle appcast.xml to a GitHub Release.

One-time secret setup

The workflow uses a Developer ID Application certificate, so the runner needs to import the certificate and private key. It discovers the imported Developer ID Application identity at runtime, so the certificate subject and Apple Team ID do not need to be committed.

  1. Export the Developer ID Application certificate + private key from your login keychain to a .p12:

    security export -k login.keychain -t identities -f pkcs12 \
      -P "<choose-an-export-password>" -o /tmp/lathe-cert.p12
    # Pick your Developer ID Application certificate
    # in the dialog that follows.
  2. Encode it as base64 (for GitHub secrets):

    base64 -i /tmp/lathe-cert.p12 | pbcopy
  3. Create an App Store Connect API Team Key for notarization and encode the downloaded .p8 file:

    base64 -i ~/Downloads/AuthKey_<KEY_ID>.p8 | pbcopy
  4. Generate a Sparkle EdDSA key and copy both keys into GitHub secrets. The public key is not sensitive, but keeping it in a secret keeps signing configuration out of the repository:

    generate_keys
    # Copy the generated public key as SPARKLE_PUBLIC_ED_KEY.
    generate_keys -x /tmp/lathe-sparkle-private-key.txt
    pbcopy < /tmp/lathe-sparkle-private-key.txt
  5. On GitHub: Settings → Secrets and variables → Actions → New repository secret. Add these secrets:

    Name Value
    SIGNING_CERT_P12 Paste the certificate base64 from step 2
    SIGNING_CERT_PASSWORD The export password from step 1
    KEYCHAIN_PASSWORD Any random string for the runner-side keychain
    APPLE_NOTARY_KEY_P8_BASE64 Paste the App Store Connect .p8 base64
    APPLE_NOTARY_KEY_ID App Store Connect API key ID
    APPLE_NOTARY_ISSUER_ID App Store Connect issuer ID
    SPARKLE_PUBLIC_ED_KEY Sparkle EdDSA public key from step 4
    SPARKLE_PRIVATE_KEY Sparkle EdDSA private key from step 4
  6. Wipe local secret copies:

    rm /tmp/lathe-cert.p12 /tmp/lathe-sparkle-private-key.txt

Cutting a release

  1. Update VERSION with the next release number, without the leading v:

    0.3.0
    
  2. Add a matching CHANGELOG.md section. The workflow uses this section as the GitHub Release body and embeds it in the Sparkle appcast:

    ## 0.3.0
    
    - Add the release notes users should see.
  3. Merge or push the release commit to the release branch:

git switch release
git merge main
git push origin release

The workflow runs, builds, signs, packages, notarizes, staples, and publishes a release with the changelog section as release notes. It also generates and uploads a signed Sparkle appcast at https://github.com/hongmono/Lathe/releases/latest/download/appcast.xml. It fails early if the VERSION value is invalid, the matching changelog section is missing, the Sparkle private key is missing, or the v<VERSION> tag already exists. You can also trigger it manually from the Actions tab → Release workflow → Run workflow (optionally override the version for a test run).

License

MIT — fork, modify, ship it however you want. Attribution keeps the door open for others to find the source.

About

Fan-shaped ⌘+Tab replacement for macOS

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0