Current version: 1.0.3
日本語 README · 简体中文 README · 한국어 README
Capsomnia is a small macOS menu bar app that turns Caps Lock into a physical keep-awake switch for closed-lid MacBook work.
Turn Caps Lock on when local work should keep running. Turn Caps Lock off when you want normal sleep behavior back.
It is useful for AI agents, mobile access, and other long-running or remote work.
Capsomnia itself does not make network requests, collect telemetry, or require an account.
When this tiny light is on, your Mac stays awake.
Requirements:
- Apple silicon Mac with macOS 14 or later
- Administrator access during installation
Install the signed package:
- Download
Capsomnia.pkgfrom GitHub Releases. - Open the package and follow the installer.
Release packages are signed with Developer ID and notarized by Apple. The package installs Capsomnia.app in /Applications, installs the signed native privileged sleep-control helper, adds a narrow sudoers rule, and starts the LaunchAgent. Capsomnia opens after installation and starts automatically at login afterward.
The package build and install scripts are public in scripts/build-pkg.sh and scripts/notarize-pkg.sh.
Developer source install still works and requires a Swift 6 toolchain:
git clone https://github.com/fuji-mak/Capsomnia.git
cd Capsomnia
./scripts/install.shThe source installer builds Capsomnia.app locally, places it in ~/Applications/, installs the same helper and sudoers rule, and starts a user LaunchAgent.
- Caps Lock on: keeps AI agents and other work from being interrupted when the MacBook lid is closed. Remote operation through tools such as Codex Mobile remains possible. The Caps Lock light physically shows the current state.
- Caps Lock off: restores normal sleep behavior.
- Lid closed while Caps Lock is on: puts the display to sleep only when no external display is connected, while work keeps running.
- Quitting the app restores normal sleep behavior.
Capsomnia is useful for long-running local jobs, AI coding agents, SSH sessions, builds, downloads, and unattended scripts.
- Ensure sufficient airflow and use a stable power source.
- Closed-lid use while sleep prevention is active may increase heat and battery consumption.
- Do not rely on Capsomnia for critical jobs or as a substitute for backups.
- Turn Caps Lock off after use and confirm that normal sleep behavior has returned.
- Use Capsomnia at your own risk. Compatibility is not guaranteed for every Mac, macOS version, or environment.
On first launch, Capsomnia explains how the Caps Lock switch works and lets you choose:
- whether to show the menu bar dot
- whether to turn the display off when the lid closes and no external display is connected
- whether to open Capsomnia at login
- English, Japanese, Simplified Chinese, or Korean
Open Capsomnia again later to change the same settings.
No Input Monitoring permission is required. Capsomnia checks the local Caps Lock state every 250 milliseconds. If you enabled Input Monitoring for an earlier version, you can disable it in System Settings.
You can open Capsomnia from /Applications/Capsomnia.app after package installation, from ~/Applications/Capsomnia.app after source installation, or from the menu bar item while it is visible.
caffeinate is useful for preventing idle sleep while your Mac is open. Closing a MacBook lid is different: normal caffeinate assertions do not reliably keep local jobs running in closed-lid use.
Capsomnia keeps work running in closed-lid use the same way it would while the lid is open. The yellow-green Caps Lock light makes that state visible.
For package installs, download and run the latest package from GitHub Releases.
For source installs, update from an existing clone:
cd Capsomnia
git pull
./scripts/install.shThe install script overwrites the app bundle, helper, sudoers rule, and LaunchAgent with the current version.
For package installs:
/Applications/Capsomnia.app/Contents/Resources/uninstall.shFor source installs:
~/Applications/Capsomnia.app/Contents/Resources/uninstall.shFrom a source clone, this is equivalent:
./scripts/uninstall.shThe uninstaller unloads the LaunchAgent, stops Capsomnia, removes Capsomnia.app from /Applications or ~/Applications, removes the helper, removes the sudoers rule, and restores normal sleep behavior. Administrator authentication may be required.
Capsomnia's menu bar app does not run as root. System sleep settings require elevated privileges, so Capsomnia uses a small fixed native helper through passwordless sudo. The helper is a compiled executable and does not invoke a shell or load shell startup files.
Package-installed app files, the helper, and the system LaunchAgent are owned by root:wheel. The packaged helper is also signed with the same Developer ID as the app. Capsomnia verifies the actual SleepDisabled state after every change and every ten seconds afterward. If the helper cannot apply a change, the state cannot be verified, or the setting drifts, the menu bar dot turns red and Capsomnia retries after five seconds instead of showing the requested state as active. The red error dot appears temporarily even if the menu bar icon is normally hidden.
Capsomnia does not request Input Monitoring or read keyboard events. It checks only the local Caps Lock state every 250 milliseconds, with timer tolerance so macOS can coalesce wakeups.
macOS may show "Taketo Fujimaki" instead of "Capsomnia" for an existing cached background-item registration. This is the LaunchAgent that starts Capsomnia at login and restarts it after crashes. Disabling it can stop automatic startup and crash recovery.
If Capsomnia is force-killed while crash recovery is disabled or unavailable, the last system sleep setting can remain active. Use the manual recovery command below to restore normal sleep behavior.
The app can only invoke:
sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset on
sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset off
sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset display-sleepThe sudoers rule is limited to those three exact commands. The helper only accepts on, off, and display-sleep, and only calls:
/usr/bin/pmset -a disablesleep 1
/usr/bin/pmset -a disablesleep 0
/usr/bin/pmset displaysleepnowLogs are written to:
~/Library/Logs/Capsomnia/
Check whether sleep is disabled:
pmset -g | grep SleepDisabledRestore normal sleep manually:
sudo pmset -a disablesleep 0Restart the LaunchAgent:
launchctl bootout "gui/$(id -u)" /Library/LaunchAgents/com.github.fuji-mak.capsomnia.plist
launchctl bootstrap "gui/$(id -u)" /Library/LaunchAgents/com.github.fuji-mak.capsomnia.plistFor source installs, use $HOME/Library/LaunchAgents/com.github.fuji-mak.capsomnia.plist instead.
Capsomnia's LaunchAgent restarts the app after a crash or other unsuccessful exit. On startup, Capsomnia reads the current Caps Lock state and reapplies the matching sleep setting. Normal Quit still exits cleanly and does not restart the app.
Check the helper permissions:
sudo -n -l /Library/PrivilegedHelperTools/capsomnia-pmset on \
/Library/PrivilegedHelperTools/capsomnia-pmset off \
/Library/PrivilegedHelperTools/capsomnia-pmset display-sleepIf the helper permission check fails, run ./scripts/install.sh again. Capsomnia checks the Caps Lock state every 250 milliseconds, so the menu bar dot may update by up to roughly a quarter second after the physical LED changes.
Capsomnia 1.0.0 is the first stable public release. See CHANGELOG.md for release history and SECURITY.md for vulnerability reporting.
MIT
