https://github.com/ddasy/sleepbar
๐ A lightweight macOS menu bar timer to auto lock, sleep, or keep your Mac awake after a countdown.
https://github.com/ddasy/sleepbar
appkit auto-lock caffeinate display-sleep keep-awake macos macos-app menu-bar menubar productivity screen-lock sleep-timer swift
Last synced: 18 days ago
JSON representation
๐ A lightweight macOS menu bar timer to auto lock, sleep, or keep your Mac awake after a countdown.
- Host: GitHub
- URL: https://github.com/ddasy/sleepbar
- Owner: ddasy
- License: mit
- Created: 2026-06-03T07:32:11.000Z (18 days ago)
- Default Branch: main
- Last Pushed: 2026-06-03T07:36:41.000Z (18 days ago)
- Last Synced: 2026-06-03T09:22:43.286Z (18 days ago)
- Topics: appkit, auto-lock, caffeinate, display-sleep, keep-awake, macos, macos-app, menu-bar, menubar, productivity, screen-lock, sleep-timer, swift
- Language: Swift
- Size: 364 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ๐ SleepBar
**A lightweight macOS menu bar timer that locks, dims, or sleeps your Mac after a countdown.**
*Set a screen-off timer before bed โ give your Mac one last task and let it auto-lock or sleep when time's up.*
**English** ยท [็ฎไฝไธญๆ](README.zh-CN.md)
---
## What is this?
Before going to sleep you often want to leave your Mac running for a little longer โ until a script finishes, an AI agent completes a task, or a download wraps up. But the macOS **"turn display off"** delay is a *fixed* setting: 5 minutes this time, 1 hour the next โ and changing it means digging into System Settings every single time.
**SleepBar** moves that control to your menu bar. Click the icon, pick a duration, and your screen stays awake for exactly that long. When the countdown ends, your Mac **automatically locks, turns off the display, or even goes to sleep** โ whatever you chose. Your task finishes, and your Mac rests.
> No system settings are modified and no `sudo` is required. The moment the timer ends, everything returns to normal.
## โจ Features
- โฑ๏ธ **Countdown screen-off** โ presets of 5 / 10 / 15 / 30 min, 1 hour, or **any custom duration**. The remaining time ticks live in the menu bar.
- ๐ **Lock screen** โ lock to the login window when time's up.
- ๐ฅ๏ธ **Turn off display** โ lock *and* power down the display to save energy.
- ๐ค **Sleep** โ put the whole Mac to sleep when the timer ends.
- โพ๏ธ **Keep awake forever (Never)** โ one click to keep the screen on indefinitely; great for long tasks, presentations, or watching videos.
- ๐ **Timed Lock** โ *โlock after **5 min** idle, for the next **2 hours**.โ* Two numbers, one sentence: how long of no input triggers a lock, and how long the whole thing runs. SleepBar then auto-locks every time you've been idle that long, re-arming after each unlock, until the time's up. The "run for" duration is a fixed countdown โ locking or unlocking never resets it. **No permissions required** (reads system idle time only, never intercepts input).
- ๐ง **Remembers your custom duration** โ your last value is saved and pre-filled, so your favorite time is one click away.
- ๐ **English / Chinese** โ switch the entire menu instantly; follows your system language on first launch.
- ๐ชถ **Extremely lightweight** โ a single Swift file, zero dependencies, no background service. **~0% CPU when idle.**
## ๐ธ Screenshots
| Chinese UI | English UI | Counting down |
|:---:|:---:|:---:|
|  |  |  |
## ๐ Installation
### Option 1 โ One line (recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/ddasy/SleepBar/main/install.sh | bash
```
### Option 2 โ Clone, then install
```bash
git clone https://github.com/ddasy/SleepBar.git
cd SleepBar
./install.sh
```
The installer automatically: **checks the Swift toolchain โ compiles โ installs locally โ sets up launch-at-login โ starts the app.** The ๐ค icon appears in your menu bar right away and **launches automatically on every login**.
> If prompted to install the *Xcode Command Line Tools*, accept it and re-run the script. That's Apple's built-in compiler toolchain โ no full Xcode required.
### Option 3 โ Download the app (DMG)
Grab the latest `SleepBar-vX.Y.Z.dmg` from the [**Releases**](https://github.com/ddasy/SleepBar/releases) page, open it, and drag **SleepBar.app** into **Applications**. Then click the menu-bar icon โ **Launch at Login** to start it automatically every time you log in.
> The DMG is ad-hoc signed but not Apple-notarized, so on first launch you may need to **right-click the app โ Open**. (The source-based options above avoid this.)
### Uninstall
```bash
./uninstall.sh
```
Stops the app, removes launch-at-login, and deletes the binary and preferences.
## ๐ฑ๏ธ Usage
Click the ๐ค icon in the menu bar:
| Section | Option | What it does |
|---|---|---|
| **Screen Off Timer** | 5 / 10 / 15 / 30 min, 1 hour | Starts a countdown; **click again to cancel** |
| | Customโฆ | Enter any number of minutes; **remembered & pre-filled** next time |
| | Never | Keep the screen on forever (menu bar shows `โ`) |
| **When Time's Up** | Lock Screen | Lock only |
| | Lock & Turn Off Display | Lock + power down the display |
| | Lock, Off & Sleep | Lock + put the Mac to sleep |
| **Timed Lock** | Timed Lockโฆ | A two-line dialog: **"Lock after `[N]` min idle"** and **"Run for `[M]` min, then stop."** Auto-locks every time you're idle that long, until the time's up. **Click again to stop.** Both values are remembered & pre-filled |
| **Language** | ไธญๆ / English | Switch the whole menu instantly |
| **Launch at Login** | toggle | Auto-start when you log in. Shown **only in the packaged app (DMG)**; the `install.sh` build already auto-starts via its LaunchAgent |
| **Quit** | | Quit SleepBar |
"When Time's Up" is a set-once, remembered preference applied at the end of every countdown.
**Timed Lock** is independent of the screen-off timer (they're mutually exclusive โ starting one stops the other). Example: at 12:00, choose *lock after 5 min idle* and *run for 120 min*. From 12:00 to 14:00 your Mac locks itself after every 5 minutes of inactivity; unlock, step away again, and it re-locks after another 5 minutes. The 2-hour countdown keeps running regardless of how often you lock or unlock.
## โ๏ธ How it works
SleepBar is a friendly menu-bar wrapper around capabilities already built into macOS:
| Feature | Under the hood |
|---|---|
| Keep awake / countdown | `caffeinate -dis -t ` (no `sudo`, auto-expires) |
| Turn off display | `pmset displaysleepnow` |
| Sleep | `pmset sleepnow` |
| Lock screen | `SACLockScreenImmediate` from `login.framework` |
| Timed Lock โ idle detection | `CGEventSource.secondsSinceLastEventType` (read-only system idle time; **no Accessibility permission**) |
| Timed Lock โ re-arm after unlock | `com.apple.screenIsUnlocked` distributed notification (event-driven, zero polling while locked) |
| Remembered preferences | `UserDefaults` (language / end action / custom duration / lock interval / window) |
Because it relies on the temporary `caffeinate` mechanism, **it never alters your system energy settings** โ the moment the timer ends, your Mac is back to its normal behavior.
## ๐ Low power by design
- **~0% CPU when idle** โ no timer runs unless a countdown is active.
- During a countdown, a single 1 Hz timer with system-coalesced `tolerance` updates only a short text label โ **no per-frame allocations**.
- **Timed Lock never busy-polls.** Instead of checking input every second, it schedules the next wake-up exactly `interval โ current idle` seconds ahead, so it wakes the CPU at most once per interval while you're active โ and while the screen is locked it does **zero polling**, simply waiting for the unlock notification. The remaining-time readout is computed only when you open the menu, not on a background tick.
- Built with `-O` (release optimization); a single binary, no embedded frameworks, no helper processes.
## ๐ ๏ธ Build from source (development)
```bash
git clone https://github.com/ddasy/SleepBar.git
cd SleepBar
./run.sh # compile and launch; re-run after edits for a hot reload
```
Or manually:
```bash
swiftc -O main.swift -o SleepBar -framework AppKit
./SleepBar
```
The whole program is a single `main.swift` (~580 lines of AppKit) with no third-party dependencies.
## ๐ Requirements
- macOS 14 (Sonoma) or later (uses the native `sectionHeader` menu API)
- Xcode Command Line Tools (`xcode-select --install`; the installer prompts you)
## โ FAQ
**Q: "Lock screen" uses a private API โ is that safe?**
A: It calls the lock function inside the system's `login.framework` (equivalent to pressing your lock-screen shortcut). It needs no Accessibility permission and sends no data anywhere. If a future major macOS release changes it, open an issue.
**Q: Will it secretly keep my Mac awake?**
A: No. The screen stays on **only** when you actively pick a duration or "Never." On launch it's idle and fully respects your system settings.
**Q: Does it survive a reboot?**
A: Yes. The installer sets up a LaunchAgent, so it reappears in the menu bar after you log in.
## ๐ Topics
A free, open-source **menu bar** utility for macOS: **auto lock screen**, **timed / recurring lock on idle**, **sleep timer**, **display sleep / screen-off timer**, **keep awake**, **prevent sleep**, and a friendly **caffeinate GUI**. A minimal, native **Swift** alternative to Amphetamine, KeepingYouAwake, and Caffeine.
Suggested GitHub topics: `macos` ยท `menubar` ยท `menu-bar` ยท `swift` ยท `appkit` ยท `caffeinate` ยท `sleep-timer` ยท `screen-lock` ยท `auto-lock` ยท `idle-lock` ยท `keep-awake` ยท `display-sleep` ยท `productivity` ยท `macos-app`
## ๐ License
[MIT](LICENSE) ยฉ 2026