clamshellctl

Control battery clamshell mode on macOS.

Important

clamshellctl is under active development and is not ready to install. The repository does not yet publish a Homebrew formula or companion-app DMG.

What it will provide

• A terminal-first clamshellctl command installed through Homebrew.
• Verified status, enable, disable, and toggle operations.
• Optional temporary enablement with automatic disablement.
• A self-contained macOS companion app with a stateful Control Centre toggle.
• One explicit administrator-authorised setup step, followed by narrowly restricted password-free operations.

The CLI will support macOS 13 and later. The optional native companion will require macOS 26 or later because that is where WidgetKit controls became available on Mac.

Temporary enablement

Use enable --for with a whole number of minutes, hours, or days:

clamshellctl enable --for 30m
clamshellctl enable --for 2h
clamshellctl enable --for 1d

The maximum duration is 30 days. The command stores an absolute deadline and uses a user LaunchAgent to disable battery clamshell mode. Sleep does not reset the duration. A new timed command replaces the current timer. enable without --for and disable cancel the current timer.

Safety model

The project changes only the Battery Power disablesleep setting. It does not change the corresponding AC Power setting.

Normal mutations will pass through a root-owned helper that accepts only the exact enable and disable operations. The sudoers policy will grant no password-free access to the public CLI, app bundle, arbitrary pmset arguments, or a shell. After each mutation, clamshellctl will reread pmset before reporting success.

Project status

The CLI, privileged helper, companion app, and Control Centre control are in active development. Automated tests cover each published behaviour.

Development

Requirements:

• macOS
• Xcode 26.6 or later
• Swift 6.3 or later

Run the current checks with:

scripts/check.sh

See CONTRIBUTING.md for setup, style, testing, and commit conventions.

Community

• Use the issue forms for bugs and feature proposals.
• Read SUPPORT.md before asking a usage question.
• Report vulnerabilities through the private process in SECURITY.md.
• Follow the Code of Conduct when participating.

Licence

clamshellctl is available under the MIT License.