Capsomnia: Caps Lock as a Closed-Lid Keep-Awake Switch on macOS
A tiny macOS app that turns Caps Lock into a physical keep-awake switch for closed-lid MacBook work.
At a glance
- What is it?
- Capsomnia is an MIT-licensed menu bar app that maps Caps Lock to sleep prevention on MacBooks, including closed-lid sessions. It is a small, opinionated tool with a privileged helper, a narrow sudoers rule, and a clear set of cases where you should not use it.
- Who is it for?
- Adopt Capsomnia if you run long local jobs or AI agents on an Apple silicon MacBook with macOS 14 or later and you want a physical, visible keep-awake switch instead of remembering a caffeinate command. Do not adopt it if you need guaranteed compatibility across every Mac and macOS version, if you cannot grant administrator access during installation, or if you want a sleep-prevention tool that does not install a privileged helper and a sudoers rule.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Capsomnia solves for closed-lid MacBooks
A MacBook that closes its lid normally goes to sleep, which stops local processes. That is the wrong default when the work is a long build, a download, an SSH session, or an AI coding agent that is expected to keep running while you are away from the machine. The usual workarounds are remembering a caffeinate invocation, changing pmset settings, or keeping the lid open, and each of those has friction: a terminal command is easy to forget, pmset changes persist beyond the session, and an open lid is not always possible. Capsomnia's answer is to make Caps Lock the switch. Turn Caps Lock on, and the Mac stays awake with the lid closed. Turn it off, and normal sleep behavior returns. The README frames the audience directly: it is useful for AI agents, mobile access, and other long-running or remote work. The physical Caps Lock light is part of the design, not an accident. The README states that the light shows the current state, so the machine's own hardware tells you whether sleep prevention is active. That is a small but real advantage over a menu bar icon you have to look for.
What the installer actually puts on the machine
Capsomnia is not a single binary you drop in /Applications. According to the README, the signed package installs Capsomnia.app into /Applications, installs a signed native privileged sleep-control helper, adds a narrow sudoers rule, and starts a LaunchAgent. The app then opens after installation and starts automatically at login afterward. That set of components is the honest cost of the design. Preventing sleep and handling closed-lid behavior requires privileges that a sandboxed menu bar app does not have, so the project splits the work: the app handles the UI and Caps Lock state, and a separate helper performs the privileged sleep control. The sudoers rule is described as narrow, and the build and install scripts are public in scripts/build-pkg.sh and scripts/notarize-pkg.sh, which means you can read exactly what the rule permits before you run the installer. The source path differs in placement: ./scripts/install.sh builds Capsomnia.app locally, puts it in ~/Applications/, installs the restricted helper and sudoers rule, and starts a user LaunchAgent. If you are evaluating Capsomnia for a managed fleet, that difference matters, because the release package and the source install do not land in the same location.
Caps Lock as a state machine, and the auto-off timer
The mechanism is a state toggle with consequences on both sides. Caps Lock on keeps agents and other work from being interrupted when the lid is closed, and the README notes that remote operation through tools such as Codex Mobile remains possible. Caps Lock off restores normal sleep behavior. Quitting the app also restores normal sleep behavior, which is the safety net if you forget the switch. Two optional behaviors change the shape of that state machine. The first is an auto-off timer: you choose a preset from 15 minutes to 8 hours or a custom duration from 1 minute to 24 hours, and when time expires Capsomnia turns off, confirms that sleep prevention is released, and immediately puts the Mac to sleep. That last clause is the one to read twice. The timer is not a passive reminder; it actively sleeps the machine. The README warns to save work and choose a duration long enough for the task to finish. The second is 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 macOS idle time or lid close, so remote UI operation such as Computer Use can continue. Those are two different goals, keeping compute alive and keeping a display session alive, and Capsomnia separates them rather than bundling them.
Caps Lock without the uppercase, and a custom toggle
Using Caps Lock as a switch creates an obvious conflict: the key still types uppercase. Capsomnia offers an optional setting that prevents all-caps typing while the app is on, so Caps Lock no longer forces uppercase input, while Shift still types uppercase letters. That is a sensible resolution, but it is opt-in, and it changes a key behavior many people rely on, so it deserves a deliberate decision rather than a default yes. For users who have already reassigned Caps Lock elsewhere, the README documents a custom toggle shortcut: turn Capsomnia on or off with another key combination even if Caps Lock is assigned elsewhere. In that configuration the green Caps Lock light continues to show the current state, which keeps the physical indicator meaningful even when the key itself does something else. This is the part of the design I find most thought through. The failure mode of most keep-awake utilities is silent state: the machine stays awake and you do not know why, or it sleeps and you do not know what changed. Capsomnia ties the state to a light on the keyboard and, optionally, to a keyboard shortcut you already use.
Installing from source versus the signed package
The README gives two installation paths with different hardware and OS requirements, and the difference is easy to miss. The signed upstream package requires an Apple silicon Mac with macOS 14 or later. A source install supports Apple silicon Macs on macOS 14 or later, or Intel Macs with macOS 13.5 or later. The README also states that the signed and notarized release package remains Apple silicon-only and requires macOS 14 or later. So Intel users are not shut out, but they are on the source path. Building from source requires Swift 5.9 or later, included with Xcode 15 or later, and the commands are short: git clone https://github.com/fuji-mak/Capsomnia.git, then cd Capsomnia, then ./scripts/install.sh. Both paths require administrator access during installation, because both install the privileged helper and the sudoers rule. Release packages are signed with Developer ID and notarized by Apple, which is the path most users should prefer if their hardware qualifies, since it avoids a local build and the Xcode dependency.
The CLI and Skill add-on, and what it is not
Capsomnia ships an optional tooling layer, and the packaging detail is worth understanding before you click install. In Advanced Settings, Download Capsomnia CLI & Skill, confirming Install 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. Two tools are involved. cpsm is the Capsomnia CLI and a common capsomnia Skill, and it requires the app; one-shot timers and explicit off include sleep. MacReady is an independent read-only Mac state CLI and a macready Skill, and it does not require the app. The app downloads the signed and notarized Tools package from the cpsm GitHub release, and Skills are shared in ~/.agents/skills/ with automatic Claude Code links. Normal CLI usage stays local. Note the phrasing in the README: one-shot timers and explicit off include sleep. If you script cpsm, a timer that expires does not merely stop preventing sleep, it puts the machine to sleep. That is consistent with the GUI timer, and it is the kind of behavior worth encoding in a wrapper rather than discovering during a job.
Limitations, failure modes, and when Capsomnia is the wrong tool
The README is unusually direct about the risks, and they are not boilerplate. Closed-lid use while sleep prevention is active may increase heat and battery consumption, and the README advises ensuring sufficient airflow and a stable power source. A MacBook in a bag with the lid shut and Caps Lock on is a machine with no airflow running a workload, which is a thermal problem regardless of how good the software is. The README also states that you should not rely on Capsomnia for critical jobs or as a substitute for backups, and that compatibility is not guaranteed for every Mac, macOS version, or environment, with use at your own risk. Those statements should shape adoption. If your workload is a production deployment or a job you cannot restart, Capsomnia is the wrong layer to depend on. The auto-off timer is another failure mode: it explicitly puts the Mac to sleep when it expires, so a timer set too short will interrupt the very task it was meant to protect. Finally, the installation model itself is a constraint. A privileged helper and a sudoers rule are a real expansion of the trust boundary, and environments that forbid both cannot use Capsomnia at all, no matter how small the app is.
How Capsomnia differs from caffeinate and pmset
The obvious alternative on macOS is the built-in caffeinate command, which prevents sleep for the duration of a process or a specified interval. The difference in approach is state versus process. caffeinate is tied to a command you launch, so its lifetime is the lifetime of that process or timer, and you manage it from a terminal. Capsomnia is a persistent toggle tied to a hardware key and a light, and it survives independently of any single job. pmset is the other comparison point, and the gap is larger: pmset changes system power settings that persist after your session ends, while Capsomnia's README states that turning Caps Lock off or quitting the app restores normal sleep behavior. That reversibility is the core design difference, and it is why Capsomnia can be described as a switch rather than a configuration change. The trade-off is that caffeinate and pmset require no privileged helper, no sudoers rule, and no installer, and they are already present on every Mac. If a single caffeinate invocation around one command solves your problem, Capsomnia adds installation surface you do not need.
Maintenance, licensing, and upgrade cost
Capsomnia is MIT licensed, which permits commercial and private use, modification, and redistribution provided the license and copyright notice are preserved. That is permissive and imposes no copyleft obligation on your own code. It says nothing about the privileged helper or the sudoers rule, which are operational and security considerations rather than licensing ones, and nothing here is legal advice. On maintenance, the repository is not archived, and the last push was on 2026-09-11, two days before this writing. Recent releases include v4.0.0 on 2026-09-08, v3.5.0 on 2026-09-06, and v3.4.0 on 2026-08-24, and the README notes multi-language documentation in Japanese, Simplified Chinese, and Korean. The upgrade cost is mostly the installer: because the package installs a privileged helper and a sudoers rule, updating is not a drag-and-drop replacement of an app bundle, and the README does not document a rollback procedure for the helper or the rule. The privacy posture is worth noting for teams that care: Capsomnia does not collect telemetry or require an account, and its only network use is an optional daily update check that reads GitHub's public release information, with an off switch in Advanced Settings, plus downloading installers from GitHub when you choose to update or install the CLI and Skill.
Editorial conclusion
Adopt Capsomnia if you run long local jobs or AI agents on an Apple silicon MacBook with macOS 14 or later and you want a physical, visible keep-awake switch instead of remembering a caffeinate command. Do not adopt it if you need guaranteed compatibility across every Mac and macOS version, if you cannot grant administrator access during installation, or if you want a sleep-prevention tool that does not install a privileged helper and a sudoers rule. Before installing, verify the release package is signed with Developer ID and notarized, read scripts/install.sh and scripts/build-pkg.sh so you know what the helper and sudoers rule do, and confirm that the auto-off timer's behavior of putting the Mac to sleep on expiry fits your workload.
Community notes