Adrafinil: Agent-Aware Sleep Control for macOS

Adrafinil prevents macOS sleep only during active AI agent sessions

Adrafinil is a macOS utility designed to keep a Mac awake—including when the lid is closed (clamshell mode)—specifically and only while AI coding agents are performing tasks. Unlike traditional "always-on" wake utilities, Adrafinil restores normal sleep behavior the moment the last active agent session releases its assertion, ensuring the machine does not stay powered on unnecessarily.

Core Features and Agent Integration

Adrafinil provides a dynamic, reference-counted system for managing power states based on actual agent activity rather than static timers or manual toggles.

Agent-Aware Wake Logic

Sleep is blocked only when one or more agent sessions hold an active assertion. When the session count drops to zero, the Mac returns to its default sleep settings, allowing it to sleep normally upon lid closure.

Native Hook Integration

Adrafinil includes a one-click installer that integrates with the hook systems of nine popular AI agents:

• Claude Code
• Codex
• Cursor
• Gemini CLI
• Aider
• Hermes
• OpenCode
• Cline
• Pi

Performance and Reliability

• Low Latency: The CLI used by agent hooks round-trips to the daemon in under 50ms to avoid stalling agent workflows.
• Thermal Protection: A thermal cutout mechanism force-releases all assertions if CPU or skin temperatures cross a safety threshold, preventing a lid-closed Mac from overheating in a bag.
• Idle Release: The system automatically drops assertions if the owning process dies or remains CPU-idle for a specified number of minutes.
• Process Sniffing: As an optional feature, the daemon can auto-acquire wake assertions by detecting known agent binaries running, even if hooks are not installed.

Technical Architecture

Adrafinil utilizes a three-tier privilege model to manage sleep settings securely while maintaining a minimal privileged surface area.

Privilege Tiers

1. Adrafinil.app: A user-facing menu bar app that handles the UI, settings, and lid-open summaries.
2. AdrafinilDaemon: A LaunchAgent running as the user. It manages the reference-counted assertion registry, monitors thermals and lid state, and handles the CLI socket.
3. AdrafinilHelper: A root-level SMAppService LaunchDaemon. This is the only component with access to sleep-blocking APIs, exposing a single setSleepBlocked(Bool) endpoint.

Sleep Blocking Mechanism

Adrafinil uses a standard IOPMAssertion for idle sleep. To override clamshell (lid-closed) sleep, it employs pmset disablesleep 1, as public IOPM assertions do not prevent sleep when the lid is closed. The helper ensures disablesleep 0 is set upon respawn to prevent state leaks after shutdown.

Requirements and Installation

Adrafinil requires macOS Tahoe 26.4 and is built with Swift 6 strict concurrency. It requires admin rights for the initial installation to register the privileged helper via SMAppService.

Community Perspectives and Alternatives

While Adrafinil solves a specific pain point for AI agent users, community discussion highlights several existing alternatives and considerations:

• Manual CLI Tools: Some users suggest using caffeinate or manual pmset commands (e.g., sudo pmset -a disablesleep 1) to achieve similar results, though these lack the agent-aware automation of Adrafinil.
• Third-Party Apps: Tools like Amphetamine are frequently cited as robust alternatives with their own set of triggers, although Adrafinil's specific focus on agent-session hooks distinguishes its workflow.
• Hardware Solutions: Some users have employed "dummy plugs" (USB-C external monitor simulators) to trick the Mac into staying awake in clamshell mode, though these can be unreliable.

"Adrafinil is the eugeroic. It does nothing until an agent acquires it, keeps your Mac awake through a closed lid only for as long as that work lives, and clears the moment the last session releases."

Comparison Summary

Feature	Adrafinil	caffeinate / pmset	Amphetamine
Agent-Aware	Yes (via hooks)	No	No (App-based)
Clamshell Support	Yes	No (public API)	Yes
Auto-Release	Yes (on task end)	Manual/Process-linked	Trigger-based
Thermal Safety	Yes	No	No