sketchybar-toggle

Daemon that coordinates SketchyBar with the native menu bar

Visit WebsiteView Source
Type
bar
License
free
Open Source
Yes
Keybindings
No
Scripting
No
Last Update
2026-03-23

Features

  • Mouse Polling at ~60Hz, No Special Permissions
  • Smooth Slide-Down Restore Animation
  • Configurable Trigger Zone and Debounce
  • Graceful Shutdown With Visibility Restore
  • Startup Recovery If Previous Instance Crashed
  • --setup Flag With Auto-Start Instructions
  • --debug Flag With Log File Output
  • Homebrew Install Via Tap

About

sketchybar-toggle is a lightweight macOS daemon written in Swift that solves the overlap conflict between SketchyBar and the native auto-hiding menu bar. It polls mouse position at ~60Hz and uses a state machine to hide SketchyBar when the cursor enters the top trigger zone, then smoothly restore it once the mouse moves away. No special macOS permissions — no Input Monitoring or Accessibility access required.

Who It's For

sketchybar-toggle is for SketchyBar users who also use macOS's native auto-hiding menu bar and are frustrated by the two bars overlapping when the cursor approaches the top of the screen. If you've noticed the native menu bar sliding down over SketchyBar every time you reach for the Apple menu, this daemon solves that problem with no configuration beyond a single line in your SketchyBar config.

How It Works

The daemon polls NSEvent.mouseLocation at ~60Hz to track the cursor's distance from the top edge of the current screen. It runs a two-state machine: in the default state, entering a configurable trigger zone (default: 10px from the top) immediately hides SketchyBar via sketchybar --bar hidden=on; once the cursor drops below the menu bar height threshold (default: 50px) and stays there through a debounce window (default: 150ms), SketchyBar is restored using its built-in slide animation. The debounce prevents flickering when the cursor briefly passes through the trigger zone.

No special macOS permissions are needed — no Input Monitoring, no Accessibility access. On startup, the daemon checks whether a previous instance crashed and restores SketchyBar visibility if needed.

Configuration

Add sketchybar-toggle to your SketchyBar config so it starts automatically. Run sketchybar-toggle --setup to detect your config format (Lua or shell) and print the exact line to add.

# In ~/.config/sketchybar/sketchybarrc (shell format):
sketchybar-toggle &

# Or with custom thresholds:
sketchybar-toggle --trigger-zone 15 --debounce 200 &

You also need topmost = "window" set in your SketchyBar bar config, and the native menu bar set to auto-hide in System Settings → Control Center. The --setup flag checks both prerequisites and warns if they're unmet.

Compared to Alternatives

There is no built-in macOS mechanism to coordinate third-party bars with the native menu bar — sketchybar-toggle fills a gap that has no other dedicated solution. Some users work around the overlap by disabling the native menu bar entirely and relying on SketchyBar for app menus too, but that requires additional SketchyBar configuration and loses native menu bar features. sketchybar-toggle is the minimal, non-destructive approach.

Requirements

  • macOS 13 Ventura or later
  • SketchyBar installed and running
  • Native menu bar set to auto-hide (Always or In Full Screen Only)
  • topmost = "window" set in SketchyBar bar config
  • No special permissions required (no SIP, no Accessibility, no Input Monitoring)

Getting Started

brew install malpern/tap/sketchybar-toggle
sketchybar-toggle --setup

The --setup command verifies prerequisites and prints the line to add to your SketchyBar config. For troubleshooting, run with --debug to log mouse position and state transitions to /tmp/sketchybar-toggle-debug.log. Full docs at github.com/malpern/sketchybar-toggle.

Discussion