Capsomnia

Product Introduction

1. Definition: Capsomnia is a lightweight, open-source macOS utility application that repurposes the hardware Caps Lock key into a physical toggle switch for system-wide sleep prevention. It operates as a menu bar app that executes privileged pmset commands via a secure helper tool.
2. Core Value Proposition: It exists to provide a simple, reliable, and visually verifiable method to keep a MacBook awake with the lid closed, enabling uninterrupted background processes like AI agent tasks, SSH sessions, long compiles, and large downloads without requiring manual terminal commands or complex energy saver settings.

Main Features

1. Hardware Toggle Integration: Capsomnia directly maps the system's sleep prevention state to the physical Caps Lock key and its LED. Activating Caps Lock triggers the app to disable system sleep via pmset -a disablesleep 1. The illuminated LED provides immediate, at-a-glance status confirmation without needing to check the menu bar or screen.
2. Secure Privileged Helper Architecture: The app employs a macOS security best-practice model. The main application runs under the user's account, while a single, minimal, root-owned helper tool (/Library/PrivilegedHelperTools/capsomnia-pmset) is installed to execute the privileged sleep commands. Access is strictly governed by a sudoers rule that only permits three specific command invocations, ensuring no arbitrary root access.
3. Transparent Open-Source Operation: Released under the MIT License, Capsomnia's entire codebase—including the Swift application, installer scripts, helper tool, and LaunchAgent plist—is publicly auditable. This transparency guarantees there is no telemetry, network communication, or hidden processes, aligning with privacy-focused user demands.

Problems Solved

1. Pain Point: MacBooks automatically initiate sleep upon lid closure, interrupting critical long-running background jobs. Traditional workarounds (like caffeinate in Terminal, adjusting Energy Saver settings, or using third-party apps) lack a quick, physical off-switch and clear status indicator, leading to failed builds, dropped SSH connections, and halted AI model operations.
2. Target Audience: Software developers and engineers running local builds or compilations; data scientists and AI researchers operating long-duration local LLM tasks (e.g., Claude Code, Codex); system administrators and DevOps professionals managing remote servers via sustained SSH sessions; and general users requiring uninterrupted large file downloads or renders.
3. Use Cases: Keeping a local AI coding assistant session active overnight with the laptop closed; ensuring a full-stack application build or Docker container compilation completes without supervision; maintaining a stable SSH tunnel to a remote development environment; allowing a multi-gigabyte software update or dataset download to finish while the MacBook is in a bag.

Unique Advantages

1. Differentiation: Unlike generic "caffeinate" apps that run in software, Capsomnia uniquely leverages existing, underutilized hardware (Caps Lock key and LED) for intuitive physical control and unambiguous state feedback. Compared to manual Terminal methods, it offers a persistent, one-touch solution without command memorization.
2. Key Innovation: Its security model is a core innovation. By constraining privilege escalation to exactly three sudo commands targeting its own helper binary—which itself only runs three specific pmset commands—it minimizes attack surface. This approach is more secure and transparent than apps requiring full disk access or running daemons with broad permissions.

Frequently Asked Questions (FAQ)

1. Is Capsomnia safe for my Mac? Yes, Capsomnia is signed, notarized by Apple, and open source. Its security model is explicitly minimal, using a confined helper tool that only runs the standard pmset command to toggle sleep settings. It makes no network requests and collects no data.
2. Does Capsomnia drain my MacBook's battery? Capsomnia itself uses negligible resources. However, by preventing sleep with the lid closed, it allows other running processes (e.g., compilers, AI agents) to consume power. Users should ensure adequate power and ventilation for extended closed-lid operation to manage heat and battery drain.
3. What happens if I quit the Capsomnia app? The app is designed to restore normal sleep behavior (pmset -a disablesleep 0) upon quit, ensuring your MacBook does not remain in a sleep-prevention state unintentionally. The Caps Lock light will turn off, and standard lid-close sleep will resume.
4. Can I use a different key instead of Caps Lock? Yes. The app's settings allow you to choose an alternative keyboard shortcut if your Caps Lock key is already assigned to another function, such as Escape or Hyper key, through system modifications.
5. Does Capsomnia work on older versions of macOS? Capsomnia requires macOS 14 (Sonoma) or later. It relies on modern macOS APIs and security frameworks for its helper installation and operation, which are not guaranteed on older operating systems.