Capsomnia

Current version: 4.0.0

日本語 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 does not collect telemetry or require an account. Its only network use is an optional daily update check that reads GitHub's public release information (off switch in Advanced Settings), plus downloading installers from GitHub when you choose to update or install CLI & Skill. Capsomnia sends no telemetry, identifiers, or personal data.

When this tiny light is on, your Mac stays awake.

Quick Start

Requirements:

• Signed upstream package: Apple silicon Mac with macOS 14 or later
• Source install: Apple silicon Mac with macOS 14 or later, or Intel Mac with macOS 13.5 or later
• Administrator access during installation

1. Download Capsomnia.pkg from GitHub Releases.
2. Open the package and follow the installer.

The package build and install scripts are public in scripts/build-pkg.sh and scripts/notarize-pkg.sh.

CLI & Skill

In Advanced Settings → Download Capsomnia CLI & Skill, confirm Install in the dialog to add both tools. Capsomnia downloads the package and installs it after macOS authentication, then shows a completion dialog. There are no agent or folder choices. The app's own package contains only the app and its helper; Capsomnia-Tools.pkg, published in the cpsm repository, adds the optional tools.

• cpsm: Capsomnia CLI and common capsomnia

• MacReady: independent read-only Mac

The app downloads the signed and notarized Tools package from the cpsm GitHub release. Skills are shared in ~/.agents/skills/, with automatic Claude Code links. Normal CLI usage stays local. Distribution and compatibility.

Build From Source

Developer source installation supports Apple silicon Macs on macOS 14 or later and Intel Macs on macOS 13.5 or later. It requires Swift 5.9 or later, included with Xcode 15 or later:

git clone https://github.com/fuji-mak/Capsomnia.git
cd Capsomnia
./scripts/install.sh

The source installer builds Capsomnia.app locally, places it in ~/Applications/, installs the restricted helper and sudoers rule, and starts a user LaunchAgent. The signed and notarized release package remains Apple silicon-only and requires macOS 14 or later.

What It Does

• Prevent all-caps typing (optional): when Capsomnia is on, Caps Lock no longer forces uppercase input. Shift still types uppercase letters.
• 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.
• Custom toggle shortcut: turn Capsomnia on or off with another key combination even if Caps Lock is assigned elsewhere. The green Caps Lock light continues to show the current state.
• Auto-off timer (optional): choose a preset from 15 minutes to 8 hours or a custom duration from 1 minute to 24 hours. When time expires, Capsomnia turns off, confirms that sleep prevention is released, and immediately puts the Mac to sleep.
• Caps Lock off: restores normal sleep behavior.
• Display behavior: by default, closing the lid puts the display to sleep while work keeps running. Enable "Keep display awake" to keep the display session available after the macOS idle time or closing the lid, so remote UI operation such as Computer Use can continue.
• Quitting the app restores normal sleep behavior.

Usage Notes

• 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.
• The auto-off timer explicitly puts the Mac to sleep when it expires. Save work and choose a duration long enough for the task to finish.
• 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.

Settings

On first launch, Capsomnia explains how the Caps Lock switch works and lets you choose:

• whether to show the menu bar dot
• whether to prevent all-caps typing while Capsomnia is on
• English, Japanese, Simplified Chinese, or Korean

The menu bar menu keeps the same day-to-day controls close at hand: choose Off or a timer preset, see the remaining time while it runs, open the custom timer editor, and toggle "Keep display awake" without opening Settings. Menu bar visibility and language remain in Settings.

macOS Accessibility permission is required only when "Prevent all-caps typing" is enabled. Capsomnia installs a local Core Graphics event filter that removes only the Caps Lock modifier from keyboard events; it does not store keyboard input or send it anywhere. If permission is missing or the filter stops, Capsomnia fails closed: sleep prevention is turned off, the menu bar dot turns red, and the app retries. When this setting is disabled, Accessibility permission is not required and Capsomnia only checks the local Caps Lock state every 250 milliseconds.

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.

Why Not caffeinate?

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.

Update

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.sh

The install script overwrites the app bundle, helper, sudoers rule, and LaunchAgent with the current version.

Uninstall

For package installs:

/Applications/Capsomnia.app/Contents/Resources/uninstall.sh

For source installs:

~/Applications/Capsomnia.app/Contents/Resources/uninstall.sh

From a source clone, this is equivalent:

./scripts/uninstall.sh

The 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.

Security Model

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.

When "Prevent all-caps typing" is disabled, Capsomnia does not request Input Monitoring or inspect keyboard events. When it is enabled, a local active Core Graphics event filter uses Accessibility permission only to remove .maskAlphaShift and suppress the Caps Lock modifier-change event. It does not log event contents, persist them, or send them over the network. Capsomnia still reads the physical Caps Lock state every 250 milliseconds to control sleep.

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 invokes these privileged commands:

sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset on
sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset off
sudo -n /Library/PrivilegedHelperTools/capsomnia-pmset display-sleep

The 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 displaysleepnow

After an auto-off timer has successfully turned Caps Lock off and confirmed SleepDisabled=0, the app runs /usr/bin/pmset sleepnow directly as the current user. This immediate sleep request does not use sudo and does not expand the helper or sudoers permissions.

Logs and Troubleshooting

Logs are written to:

~/Library/Logs/Capsomnia/

Check whether sleep is disabled:

pmset -g | grep SleepDisabled

Restore normal sleep manually:

sudo pmset -a disablesleep 0

Restart 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.plist

For 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-sleep

If 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.

Project Status

Capsomnia 1.0.0 is the first stable public release. See CHANGELOG.md for release history and SECURITY.md for vulnerability reporting.

License

MIT