Capsomnia: using the Caps Lock light as a keep-awake switch on a closed MacBook

The problem: a closed lid kills the job

A MacBook that closes its lid normally sleeps. That is fine for a person, and wrong for a build, a download, an SSH session, or a local coding agent that is halfway through a task. The usual workarounds are external displays, third-party keep-awake utilities, or `caffeinate` in a terminal, and each has a cost: a display changes the physical setup, a terminal command is invisible once the window is buried, and a utility that lives only in the menu bar gives no signal from across the room.

Capsomnia takes the Caps Lock key and its hardware LED as the control surface. The README states the intent plainly: "Turn Caps Lock on when local work should keep running. Turn Caps Lock off when you want normal sleep behavior back." The light on the key is the state readout. That is the whole idea, and it is a better fit for a laptop than a menu bar toggle because the indicator is on the keyboard, not behind a screen that may be asleep.

The audience is narrow on purpose. The README names AI agents, mobile access, and other long-running or remote work. If your work finishes in seconds, this app adds a privileged helper and a sudoers rule for no benefit.

What actually happens between the key and the sleep state

The installer is where the mechanism becomes visible. According to the README, the package installs `Capsomnia.app` into `/Applications`, installs a signed native privileged sleep-control helper, adds a narrow sudoers rule, and starts a LaunchAgent. The helper is the piece that can change sleep behaviour; the app itself is a menu bar front end. The sudoers rule exists so the app can invoke that helper without prompting for a password on every toggle.

That split explains the permission story. Capsomnia is not a kext and not a kernel extension. It is a user-space app plus a privileged binary, which is why the README insists on administrator access during installation and why it points at `scripts/build-pkg.sh` and `scripts/notarize-pkg.sh` as public build and install scripts.

State is expressed in three places at once: the Caps Lock LED, the menu bar item, and the actual sleep assertion held by the helper. The README also notes that quitting the app restores normal sleep behaviour, so the helper's assertion is tied to the app's lifetime rather than surviving as an orphaned setting.

One design detail worth pausing on: when Capsomnia is on, Caps Lock no longer forces uppercase input, and Shift still types uppercase letters. The key is repurposed as a switch, so anyone who genuinely relies on Caps Lock for typing must either accept the change or bind the custom toggle shortcut the README describes.

Installing Capsomnia and running a first closed-lid job

The signed path is the short one. Download `Capsomnia.pkg` from GitHub Releases, open it, and follow the installer. The README states the package is signed with Developer ID and notarized by Apple, that it needs an Apple silicon Mac with macOS 14 or later, and that administrator access is required during installation. Capsomnia opens after installation and starts automatically at login afterward.

If you prefer to build it yourself, the README gives this sequence. It requires Swift 5.9 or later, which ships with Xcode 15 or later, and it supports Apple silicon Macs on macOS 14 or later plus Intel Macs on macOS 13.5 or later. The source installer puts the app in `~/Applications/` rather than `/Applications/`.

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

After either install, the first real use is a two-step check. Start a job that must not be interrupted, turn Caps Lock on, and confirm the key's green light is lit and the menu bar item agrees. Close the lid. The README says that by default closing the lid puts the display to sleep while work keeps running; if you need the display session to stay available for remote UI operation, enable "Keep display awake" so the session survives the macOS idle time or lid close.

For a bounded run, set the auto-off timer before you walk away. The README lists presets from 15 minutes to 8 hours and a custom duration from 1 minute to 24 hours. When the timer expires, Capsomnia turns off, confirms that sleep prevention is released, and immediately puts the Mac to sleep. That last clause is the one to internalise: save your work first.

The auto-off timer is a trap if you read it as a safety net

Most keep-awake tools fail by staying on too long. Capsomnia's timer fails in the other direction. The README is explicit that when the timer expires the app turns off, confirms sleep prevention is released, and immediately puts the Mac to sleep. A duration chosen too short does not merely stop preventing sleep; it actively sleeps the machine mid-task. The usage notes repeat the warning: save work and choose a duration long enough for the task to finish.

The README also lists constraints that no amount of configuration removes. Closed-lid use while sleep prevention is active may increase heat and battery consumption. Sufficient airflow and a stable power source are the user's responsibility. And there is a blunt line about scope: do not rely on Capsomnia for critical jobs or as a substitute for backups, with use at your own risk and no guaranteed compatibility for every Mac, macOS version, or environment.

Read those together and the correct deployment shape is a laptop on a desk with air around it, plugged in, running a job whose failure you can tolerate. A MacBook sealed in a bag running an overnight agent is exactly the case the documentation warns about. There is no thermal telemetry in the app to tell you the machine is cooking.

Capsomnia CLI, the Skill, and how they differ from the app alone

The optional tools live in a separate package. The README states that the app's own package contains only the app and its helper, while `Capsomnia-Tools.pkg`, published in the cpsm repository, adds the optional tools. Installation happens through Advanced Settings, then Download Capsomnia CLI & Skill, then confirming Install in the dialog. Capsomnia downloads the package and installs it after macOS authentication, and there are no agent or folder choices.

Two tools arrive. `cpsm` is the Capsomnia CLI plus a common `capsomnia` Skill; it requires the app, and the README notes that one-shot timers and explicit off include sleep. MacReady is a separate read-only Mac state CLI with a `macready` Skill that does not require the app. Skills are shared in `~/.agents/skills/`, with automatic Claude Code links, and normal CLI usage stays local.

That split matters for scripting. If you want a job to wake the machine's sleep state for a fixed window without touching the Caps Lock key, the CLI is the relevant surface, and the app is a prerequisite. If you only want to read machine state, MacReady is independent and carries no privileged helper of its own.

How Capsomnia compares with caffeinate and Amphetamine

The closest baseline is `caffeinate`, which ships with macOS. It is a command you run, it holds a power assertion for as long as the process lives, and it has no GUI, no LED, and no installer. Capsomnia's difference is not the assertion itself but the control and feedback loop: a physical key with a light, a menu bar item, an optional custom shortcut, and an auto-off timer. If you are comfortable with a shell and you already know whether your job is running, `caffeinate` costs nothing and installs nothing.

Against GUI keep-awake utilities, the difference is the privileged helper plus sudoers rule that Capsomnia installs at system level, and the deliberate repurposing of Caps Lock so the keyboard itself is the switch. That is also the trade: you give up Caps Lock's normal function, and you accept a persistent privileged component on the machine. A tool that only lives in the menu bar asks for less.

The honest summary is that Capsomnia is not doing something the operating system cannot do. It is making the toggle physical and legible, which is the entire value proposition, and it is worth adopting only if that legibility is what you were missing.

Maintenance, upgrades, and the MIT licence

The repository is not archived, and the last push was on 2026-09-11, with v4.0.0 released on 2026-09-08, v3.5.0 on 2026-09-06, and v3.4.0 on 2026-08-24. Those dates describe a project that has been shipping recently, and the changelog file at the repository root is where the upgrade story lives. The README does not document rollback, so if you need a downgrade path you will be working it out from the releases yourself.

Upgrade cost has two parts. The app updates through its optional daily update check, which the README says reads GitHub's public release information and can be switched off in Advanced Settings. The privileged pieces are the heavier part: the helper and the sudoers rule are installed at system level, so a reinstall or a source build touches system configuration again, and the source path requires Xcode 15 or later and Swift 5.9 or later on the build machine.

The licence is MIT. That permits use, modification, and redistribution with the licence and copyright notice preserved. It does not change the risk posture the README already states: no compatibility guarantee, no warranty, and an explicit instruction not to rely on it for critical jobs. Nothing here is legal advice, and if you redistribute a modified build, the trademark and attribution questions are yours to check.

Editorial conclusion

Capsomnia suits people who run long local jobs on an Apple silicon MacBook and want a physical, glanceable indicator that sleep is blocked. It is the wrong choice if you need verified uptime guarantees, Intel Macs on the signed package, or unattended overnight runs without airflow. Before adopting it, check the macOS 14 requirement, confirm the sudoers rule and helper land where the install scripts say they do, and read the auto-off timer behaviour, which puts the Mac to sleep when it expires.

Frequently asked questions

Official sources

1. fuji-mak/Capsomnia on GitHub
2. License: MIT
3. Project website
4. README
5. Releases