Proposal: simplify awake controls and make closed-lid operation safer

[airhunter]

Summary

The current menu makes it difficult to understand what will happen when the screen locks, the display turns off, or the lid is closed.

I propose renaming the controls based on their actual outcomes, simplifying the screen behavior, and giving closed-lid operation its own safety timeout.

Current behavior

Based on the current implementation:

• Keep Mac Awake prevents idle system sleep.
• When Allow Lock & Sleep is enabled, the screen may lock or turn off while the Mac and background tasks continue running.
• When Allow Lock & Sleep is disabled, Code Awake also prevents display sleep.
• Allow Closed Lid adds a best-effort assertion intended to keep the Mac running with the lid closed.
• Auto Turn Off disables the entire awake session after the selected duration.
• The screen-dimming feature displays a dark overlay instead of putting the display to sleep.

Relevant implementation:

https://github.com/artemsvit/Code-Awake/blob/v1.0.11-build-18/Code%20Awake/AppLogic.swift#L15-L45

Problems

1. “Allow Lock & Sleep” is unclear as a complete option

Taken as a whole, Allow Lock & Sleep sounds as though enabling it allows the Mac itself to lock and enter system sleep. This also appears to conflict with the main Keep Mac Awake switch.

The option does not explain:

• whether “Sleep” refers to the display or the entire system;
• whether the Mac remains awake;
• whether background tasks continue running.

Its actual behavior is much more specific: the display may turn off and the session may lock, while the Mac and background tasks continue running.

A clearer outcome-oriented label would be:

Continue Running When Screen Is Locked or Off

2. “Allow Closed Lid” does not describe the outcome

The current label does not say what is being allowed.

It could be interpreted as:

• allowing the Mac to sleep after the lid is closed; or
• allowing the Mac and background tasks to continue running.

A clearer label would be:

Continue Running with Lid Closed

Because the current implementation is best-effort, this limitation could be explained in a tooltip or subtitle rather than being hidden from the user.

3. The screen-dimming overlay has limited practical value

The current screen-dimming feature displays a dark overlay instead of putting the display to sleep or reducing the hardware backlight.

This does not clearly solve any of the main use cases:

• If the goal is to save power, actual display sleep is more effective.
• If the goal is privacy or security, the overlay is not a screen lock.
• If the goal is to keep information visible, the overlay hides most of the content.
• It does not provide the same behavior across built-in and external displays.

This creates another screen state that users must understand, without providing the main benefits of either keeping the display awake or allowing it to sleep.

I suggest removing this feature from the primary interface. If it is retained, it could be moved to an advanced section and clearly described as a visual overlay rather than display sleep.

4. The global timer does not fit every usage scenario

Continuing to run while the screen is locked or off can be a normal, persistent preference. Some users may reasonably want to leave this enabled without a time limit.

Closed-lid operation has a different risk profile. If it is accidentally left enabled and the Mac is placed in a bag, it may cause unnecessary battery drain and heat buildup.

With the current global timer, the user must choose between:

• limiting the entire awake session, even when only closed-lid operation needs a safety limit; or
• selecting Infinity, which also removes protection from forgotten closed-lid operation.

The existing controls mostly represent operating states or preferences, while the global timer treats them as one temporary session. These two models do not fit together particularly well.

Proposed design

Keep Mac Running                              [ On ]

Continue Running When Screen Is Locked or Off [ On ]

Continue Running with Lid Closed              [ Off ]
    Maximum Closed-Lid Runtime                 [ 2 hours ]

Keep Mac Running

This is the main switch.

When it is disabled, normal macOS power behavior applies. When it is enabled, Code Awake prevents idle system sleep so background tasks can continue running.

Continue Running When Screen Is Locked or Off

When enabled:

• the display follows normal macOS settings;
• the display may turn off;
• the session may lock;
• the Mac and background tasks continue running.

When disabled, Code Awake also keeps the display awake.

This provides two understandable outcomes through a single setting, without requiring the screen-dimming overlay.

Continue Running with Lid Closed

This controls the additional best-effort closed-lid behavior.

It should be disabled by default and have an independent safety timeout.

Ideally, the closed-lid timer would:

1. start when the lid is actually closed;
2. stop and reset when the lid is opened;
3. provide the full configured duration on the next lid closure;
4. disable only closed-lid operation when it expires;
5. leave normal open-lid awake behavior unchanged;
6. show a warning shortly before it expires.

A default limit of one or two hours would provide a safer default.

An unlimited option could still be available as an advanced choice, with a warning explaining the battery and heat implications of leaving the Mac running with its lid closed.

Existing global timer

If the existing global timer is retained, it could be moved to an advanced section and renamed to something explicit, such as:

Stop Awake Mode After

This would make it clear that it ends the entire awake session and is separate from the closed-lid safety timeout.

Why this matters

Code Awake is often used for downloads, builds, servers, backups, and other unattended tasks.

In these situations, users need to understand three things immediately:

• Will the task continue when the screen turns off or locks?
• Will the task continue after the lid is closed?
• When will closed-lid operation stop?

Unclear controls can lead to either an interrupted task or a Mac unintentionally continuing to run with its lid closed.

The proposed design makes the outcomes explicit while providing a safer default for the higher-risk closed-lid scenario.

Willing to help

If this direction fits the project, I would be happy to help refine the behavior and wording, discuss implementation constraints, and contribute the changes after the expected behavior is agreed upon.