Open Caffeine

Product Introduction

1. Definition: Open Caffeine is a native macOS menu bar application and system utility written in Swift. It functions as a Caffeine-style tool designed to temporarily prevent a Mac from going to sleep, with granular control over system sleep, display sleep, and automatic termination.
2. Core Value Proposition: This open-source utility exists to provide macOS users with a simple, modern, and trustworthy solution to keep their Mac awake for specific durations, eliminating the need to navigate complex pmset terminal commands or use bloated applications with unnecessary features. Its core value is delivering reliable, configurable, and battery-aware sleep prevention with a native user experience.

Main Features

1. Preset & Custom Timers: Open Caffeine provides quick-select presets (e.g., 5 minutes, Forever) and a custom duration prompt for setting precise wake periods. Technically, this manages a CaffeineSession with a countdown timer, displaying the remaining time directly in the macOS menu bar next to its icon, ensuring users have constant, clear feedback on the remaining active session.
2. Granular Sleep Control: The app offers a toggle to "Keep the screen on." When enabled, it uses macOS IOKit assertions to prevent both system sleep (PreventUserIdleSystemSleep) and display sleep (PreventUserIdleDisplaySleep). When disabled, it only prevents system sleep, allowing the display to turn off while keeping the Mac running for background tasks. This distinction is crucial for power management and is a key technical feature.
3. Global Hotkey & Menu Bar Integration: Users can toggle the Caffeine state on/off using a configurable global keyboard shortcut, managed by the HotKeyService. The primary interface is a persistent macOS menu bar (NSStatusItem) with a customizable icon style, accessible via the MenuBarController for immediate access without navigating application windows.
4. Battery Threshold Safety: A built-in BatteryMonitor service watches the system's battery level. If the battery drops below a user-defined threshold (e.g., 20%), it automatically stops the active Caffeine session to prevent complete battery drain, a critical fail-safe for laptop users that many similar utilities lack.
5. 100% Code Coverage & Open Source: The entire codebase is open source under the MIT license, fostering transparency and community trust. It is built with XcodeGen, uses SwiftLint for code quality, and enforces a 100% line-coverage gate on all logic files (excluding UI shells) via a pre-push hook, ensuring high software quality and reliability.

Problems Solved

1. Pain Point: Standard macOS energy saver settings force the Mac to sleep after a period of inactivity, interrupting long downloads, video rendering, scientific computations, presentations, or remote access sessions. Manually configuring sleep prevention via Terminal commands (caffeinate -i) is unintuitive for many users.
2. Target Audience: Software developers running long build processes, data scientists executing model training, designers exporting large files, presenters and meeting hosts, remote workers needing persistent access, and media professionals (e.g., for audio playback or video transcoding). Essentially, any macOS user needing to temporarily override the default sleep behavior.
3. Use Cases: Keeping a Mac awake during a lengthy file download or upload, preventing sleep during a software compilation, maintaining system activity while streaming media to a home theater, ensuring the Mac stays on for a scheduled Time Machine backup, and preserving a desktop state for a live demonstration or classroom lecture.

Unique Advantages

1. Differentiation: Unlike the classic "Caffeine" app or App Store alternatives like "Amphetamine," Open Caffeine is fully open source, meaning its code is auditable for security and privacy. It is built as a native Apple Silicon binary (Universal) with a modern SwiftUI Preferences interface, and it avoids the common practice of bundling marketing-focused "menu bar items" or promotions. It focuses purely on its core utility.
2. Key Innovation: The combination of a configurable global hotkey, a visible countdown timer, explicit screen-sleep control, and an intelligent, automatic battery threshold stop creates a uniquely robust and user-conscious feature set. The enforcement of 100% test coverage on its logic layer is a significant engineering innovation for this class of utility, ensuring stability and correctness.

Frequently Asked Questions (FAQ)

1. What is the difference between "Keep the screen on" ON and OFF in Open Caffeine? When "Keep the screen on" is ON (default), Open Caffeine prevents both your Mac and its display from sleeping. When it is OFF, it only prevents the entire Mac system from sleeping, but allows the display to turn off after the macOS display-sleep timer elapses, which can save screen power while keeping processes running.
2. How do I install Open Caffeine? Is it on the Mac App Store? Open Caffeine is not on the Mac App Store. You can install it by building it from source using Xcode or by downloading the pre-built .app zip file from the latest GitHub Release. It is an unsigned binary, so you may need to adjust your security settings to open it the first time.
3. Does Open Caffeine work on Intel Macs or is it only for Apple Silicon? Open Caffeine is built as a Universal Binary. The project description notes it is "Apple Silicon native," meaning it is optimized for M-series chips, but it is fully compatible with Intel-based macOS devices running macOS 26 (Tahoe) or later.
4. How does the auto-update mechanism work? Open Caffeine uses the Sparkle framework for secure, transparent auto-updates. The app checks an appcast.xml feed hosted on the GitHub repository. Updates are cryptographically signed (EdDSA), ensuring only verified releases from the developer are installed.
5. Can I contribute to the project or report an issue? Yes. As an open-source MIT-licensed project on GitHub, you can contribute code via pull requests, report bugs in the Issues tab, and review the detailed documentation in the repository, including the design specification. Contributions are guided by the CONTRIBUTING.md file.