Documentation
All Applications/Coffee/Essentials/Display Modes

Display Modes

Understanding screen-on, system awake states, and clamshell mode functionality.

Coffee gives you precise control over how your Mac handles sleep. It interfaces directly with macOS's low-level power management APIs (IOPMAssertionCreateWithName) to prevent your system from entering sleep mode when you need it most.

Screen On vs System Awake

Coffee offers two distinct modes of operation, depending on what you're trying to achieve:

  • Keep Display On: This is the default mode. It prevents both the display from dimming/turning off and the system from sleeping. This is ideal when you are reading a long document, monitoring a dashboard, or giving a presentation.
  • Keep System Awake (Display Off allowed): In this mode, Coffee allows your screen to turn off normally according to your macOS Energy Saver settings, but it prevents the CPU and hard drives from sleeping. This is perfect for long background downloads, rendering video, or running a local server overnight.

Clamshell Mode

By default, macOS forces your MacBook to sleep when you close the lid, unless you are connected to power and an external display.

Coffee can override this behavior. If you enable Clamshell Mode in the settings, you can close your MacBook's lid, and Coffee will force the system to stay awake. This allows you to throw your MacBook in a bag while it finishes downloading a massive file, or run a headless server without needing an external monitor attached.

Warning: Be careful when using Clamshell mode in a confined space (like a tightly packed backpack). Intense tasks like video rendering generate heat, and a closed MacBook relies heavily on its keyboard deck for thermal dissipation.