Adrafinil: Conditional Sleep Prevention for AI Coding Agents on macOS

Adrafinil: Conditional Sleep Prevention for AI Coding Agents on macOS

Adrafinil is a macOS utility designed to keep a Mac awake only during active AI coding agent sessions, allowing the system to sleep normally when no work is being performed. Unlike always-on wake utilities, Adrafinil dynamically blocks sleep—including clamshell (lid-closed) sleep—only while an agent is mid-task, automatically releasing the hold once the session concludes.

Agent-Aware Sleep Management

Adrafinil prevents the system from sleeping exclusively when one or more AI coding agent sessions hold an active assertion. When no sessions are active, the Mac's default sleep behavior remains untouched. This approach differs from tools like caffeinate or Amphetamine, which typically maintain a constant state of wakefulness regardless of actual system activity.

Supported Agents and Integration

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

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

Integration is handled via a bundled CLI that agents call to acquire a session key when a task starts and release it when the agent goes idle. These CLI calls are optimized for sub-50ms round-trips to ensure they do not stall the agent's workflow.

Technical Architecture and Security

Because overriding clamshell sleep requires root privileges, Adrafinil uses a tiered architecture to minimize the privileged attack surface.

Privilege Tiers

  1. Adrafinil.app: A user-facing menu bar application that handles the UI, settings, and lid-open summaries.
  2. AdrafinilDaemon: A LaunchAgent running as the user. This component manages the reference-counted assertion registry, monitors thermal and lid states, 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 simple setSleepBlocked(Bool) method. It verifies the caller's code-signing requirement before executing commands.

Sleep Blocking Mechanism

Adrafinil uses a standard IOPMAssertion for idle sleep. To handle clamshell sleep, it employs pmset disablesleep 1. The developer notes that public IOPM assertions (used by caffeinate) are insufficient for keeping a lid-closed Mac awake. To prevent state leaks, the helper resets disablesleep to 0 upon respawning before re-applying the current state.

Safety and Monitoring Features

To prevent hardware damage and ensure system stability, Adrafinil includes several automated safeguards:

  • Thermal Cutout: If the CPU or skin temperature exceeds a predefined threshold while the lid is closed, all assertions are force-released to prevent the Mac from overheating in a confined space (e.g., a laptop bag).
  • Idle Release: Assertions are automatically dropped if the owning process dies or remains CPU-idle for a specified number of minutes.
  • Lid-State Feedback: A chime sounds upon closing the lid to confirm an assertion is held. Upon reopening, the user is presented with a summary of what ran, the peak temperature reached, and whether a thermal cutout occurred.

Requirements and Installation

Adrafinil requires macOS Tahoe 26.4 (or potentially earlier 26.x versions) and is built using Xcode 26+ with Swift 6 strict concurrency. Installation requires admin rights to register the privileged helper via SMAppService.

Community Perspectives

While the tool solves a specific pain point for AI agent users, some community members have suggested simpler alternatives or raised concerns:

  • Existing Tools: Some users pointed out that apps like Amphetamine can end when a specific app closes, or that simple shell scripts using pmset can achieve similar results.
  • Hardware Risks: Users reminded the developer that laptops cannot cool effectively inside backpacks, which justifies the inclusion of the thermal cutout feature.
  • Manual Alternatives: One user suggested using dummy HDMI/USB-C plugs to simulate an external monitor to prevent sleep, though they reported inconsistent results.

"I used to do this 15 years ago to keep listening to music from my laptop... One caveat, your laptop cannot cool inside a backpack, it will overheat and shut down anyway."

Summary of CLI Commands

Command Purpose
acquire <key> Blocks sleep when an agent turn starts
release <key> Unblocks sleep when the agent goes idle
hold --for <time> Time-boxed wakefulness for background tasks (e.g., deploys)
mcp Enables Model Context Protocol communication on stdio
status Checks current assertion state

Sources