Clamshell 0.5.0

Built from 3cfae85 by CI.

Clamshell-0.5.0.pkg (sha256 d4389c25e1422ec3ebe83c69fa8fc35890b80df5bb5b9b09b5afa87185d5e5b3) installs the CLI, the root-owned helper with its narrow sudoers rule, and the menu bar app.

See CHANGELOG.md for details.

Clamshell 0.4.0

Check GitHub Releases for a newer version and install it with consent.

Added

• clamshell update checks GitHub Releases for a newer version, and clamshell update --install downloads, verifies and installs it. The check is throttled to once a day (--force overrides), and the result is available as JSON with --json for the menu bar app.
• The menu bar app checks for updates in the background and offers Update to X.Y.Z… when one is available, next to an always-present Check for Updates… row. Installing always asks for confirmation first, and the app offers to restart once the new version is in place.
• The installer is verified against the release's sha256 digest before it is installed. A release without a digest is refused unless --allow-unverified is passed, so the default path never installs unverified code. --dry-run downloads and verifies without installing.
• An active keep-awake session is re-armed on the new version after an upgrade, so the new watcher takes over without restoring sleep. The updated sources are also copied into the user-owned support directory, which the menu bar app reads.

Changed

• Release selection prefers a final release over a pre-release and only ever offers something strictly newer than the running version. With this project's releases currently all marked as pre-releases, the newest pre-release is offered instead, so updates still work either way.

Notes

• Requires macOS 14 or newer on Apple Silicon.
• The app is an accessory (LSUIElement): a moon glyph in the menu bar, no Dock icon.
• Clamshell-0.4.0.pkg (sha256 8dc8d405dd3209659ec9232dfaf770121f30da6953d9503002c6921aa92397c4) installs the CLI, the root-owned helper with its narrow sudoers rule, and the menu bar app.

See CHANGELOG.md for details.

Clamshell 0.3.0

Blank the built-in panel when the lid closes, and align a session across restarts.

Added

• clamshell reconcile re-aligns a pending session after a restart: a trigger still in the future is re-armed with the remaining time, and one that already passed restores sleep instead of leaving it disabled forever. The menu bar app runs it at launch.
• clamshell status --json and clamshell battery --json emit machine-readable state. The menu bar app reads the JSON form, falling back to the text parser for an older CLI.
• clamshell darken blanks the display on demand, so the menu bar toggle also applies to a session that is already running.
• The menu bar app remembers the chosen battery floor, duration, custom span and display toggle across launches.
• clamshell on now always starts the session watcher, including for an unlimited session with no time limit and no battery floor.

Fixed

• The built-in display is now blanked when the lid closes. With sleep disabled macOS does not do this on its own: the idle display timer normally handles it, and on battery that timer is off, so a shut lid could leave the panel lit. The session watcher blanks it again on every pass, and skips that when an external display is attached or any probe fails.
• clamshell off restores sleep before cancelling the timer, so a cancellation cannot leave sleep disabled with no trigger and no state file.
• The watcher retries a failed restore, logs to ~/Library/Logs/clamshell.log, and keeps the state file so a refused sudo cannot let the battery drain unnoticed.
• A duration longer than 30 days is rejected by the CLI, matching the limit the menu bar app already enforced.
• The menu bar no longer crashes when the status menu is rebuilt while it is still installed.
• The menu checks the duration that is actually running, and nothing is checked when a custom span is in use.
• A command that times out keeps the child's stderr in the error message, truncated so a runaway log cannot bloat the alert.
• The menu bar no longer hangs for the full command timeout when the CLI writes more than the ~64 KiB pipe buffer.
• A CLI error is now shown in front of the active app, and the countdown keeps ticking while the menu is open.
• clamshell status reports a reached battery floor even when a time limit is also active.
• The helper rotates its log through a mktemp file and keeps logging when a rotation step fails.
• The version test compares both Info.plist keys through plistlib, so a bundle whose version strings drifted apart is caught.
• package.sh fails with a clear message when the version cannot be read and ships only the known modules.

Documentation

• README states the current version, documents the helper log and state-file paths, and no longer implies the helper copy under ~/Library/Application Support/clamshell/ is what runs as root.

Notes

• Requires macOS 14 or newer on Apple Silicon.
• The app is an accessory (LSUIElement): a moon glyph in the menu bar, no Dock icon.
• Clamshell-0.3.0.pkg (sha256 38d8cee712165b5c347736c5d145b1634b3f4e6e24e1314e07061499701a863a) installs the CLI, the root-owned helper with its narrow sudoers rule, and the menu bar app.

See CHANGELOG.md for details.

Clamshell 0.2.0

Enter a custom duration and battery floor by hand.

Added

• Custom… under the duration choices accepts 45m, 2h, 1h30m, 1h 30m, or a bare number read as minutes. Zero groups are dropped (0h30m → 30m), and a 30-day ceiling rejects typos like 999999999, which would otherwise create an effectively endless session.
• Custom… under the battery floor accepts any whole level from 5% to 95%, with or without a percent sign. The range matches the CLI, so invalid input is caught in the UI instead of failing in a subprocess.
• A hand-entered value is validated before use and then shown as a checked menu row, so the selection stays visible even when it matches no preset.

Notes

• Requires macOS 14 or newer on Apple Silicon.
• The app is an accessory (LSUIElement): a moon glyph in the menu bar, no Dock icon.

See CHANGELOG.md for details.

Clamshell 0.1.1

Fixes a bug that could keep the Mac awake indefinitely.

Fixed

The menu bar app opted out of App Nap with .userInitiated, which also sets the idleSystemSleepDisabled bit. The app therefore held a power assertion for as long as it ran, so after a timed session expired the Mac stayed awake instead of sleeping — the opposite of what the tool is for.

It now uses .userInitiatedAllowingIdleSystemSleep, which keeps the countdown timers responsive without blocking sleep. The policy lives in AppNapPolicy with a regression test asserting it never blocks idle sleep.

If you installed 0.1.0, upgrade: until you do, quit the app when you want the Mac to sleep normally.

Install

Download Clamshell-0.1.1.pkg below, open it and follow the installer.

The package is not notarised, so the first launch may need System Settings → Privacy & Security → Open Anyway.

See CHANGELOG.md for details.

Clamshell 0.1.0

First pre-release.

Superseded by 0.1.1.
This build has a bug: the menu bar app prevents system sleep for as long as it
runs, because it opted out of App Nap with an option that also disables idle
sleep. Upgrade to 0.1.1.

macOS sleeps as soon as the lid closes unless sleep is disabled, and on Apple Silicon neither caffeinate nor ordinary keep-awake apps can override that. Clamshell wraps the only working switch, pmset disablesleep, in a root-owned helper with a narrow NOPASSWD sudoers rule.

• clamshell on / off / status / battery
• --for SPAN restores sleep after a duration
• --battery PERCENT restores sleep at a battery floor, applied only while unplugged
• --darken blanks the display immediately
• Menu bar app with a live countdown, battery floor selection, display toggle and surfaced CLI errors

See CHANGELOG.md for details.