Lid closed, in a bag, on battery, no external display: your processes, SSH sessions, dev servers and AI coding agents keep running as if the lid were open. One switch in the menu bar for you, three commands for your agents.
No release yet — the first build ships right after the closed-lid battery test
on the target M4. Until then, build it yourself: scripts/build.sh.
How it works
caffeinate and sleep assertions stop idle sleep, but not the sleep
macOS triggers the instant the lid clicks shut. Shutlid uses the one setting the kernel checks before
every kind of sleep, including that one.
From the menu bar, or shutlid on from an agent. One admin authorization the first time; never again after that.
The system-wide sleep veto is already set. No external display, keyboard or mouse required — on battery or AC.
24 hours by default, or off entirely with shutlid off. A restart always returns to normal sleep.
Built to be boring
Reliability first. One file talks to macOS power management. Everything else is plain, readable Swift with no dependencies to rot.
Setup installs a sudo rule scoped to five literal commands: the sleep flag on or off, and the battery Energy Mode. After that, no custom code ever runs as root.
24 hours by default, adjustable from 1 hour to never. And while the lid is closed, the battery switches to Low Power Mode so a bag stays cooler.
Three commands, stable exit codes, no GUI automation and no password prompts after setup.
A reboot always returns to normal sleep by default, whether or not the app is even opened.
status reads the kernel fresh every time. If macOS isn't preventing sleep, it says so.
Swift Package Manager, no Xcode project, no third-party packages. Understandable in fifteen minutes.
For humans and agents alike
The CLI is the agent interface: no GUI automation, no interactive prompts after the one-time setup. Results go to stdout, errors to stderr, and exit codes are documented and stable.
# an agent, mid-task
$ shutlid on
Requested: ON
Effective: ON
Mode: always
Auto-off: in 23h 59m
# hours later, job done
$ shutlid off
Requested: OFF
Effective: OFF
Mode: always
Auto-off: 24hshutlid on [--for <hours>]
shutlid off
shutlid status
shutlid setup
shutlid log| Command | 0 | 1 | 2 |
|---|---|---|---|
| on, off | done | error | setup required |
| status | keeping awake | normal sleep | — |
Why not just…
Sourced from the full write-up in RESEARCH.md, including every approach that was tried and rejected.
| Approach | Survives lid close | Works on battery | Needs a display/peripheral | Extra moving parts |
|---|---|---|---|---|
| Shutlid | Yes | Yes | No | None |
caffeinate / sleep assertions | No | — | No | None |
| Apple clamshell mode | Yes | No | Display + AC + input | None |
| Virtual-display trick | Yes | No | No | Mouse jiggle, assertions, virtual display |
Security model, stated plainly
shutlid off, sudo pmset disablesleep 0, or a reboot returns the Mac to normal sleep.Full disclosure in the README: after setup, any process running under an admin account on the machine can toggle sleep prevention without a password. It cannot gain root or run anything else — see the security model for the complete threat statement.
FAQ
That is the scenario it is built for. It sets the same power-management flag the kernel checks before any sleep, so no display or keyboard needs to be attached. The on/off toggle has been verified against the real kernel flag on an M4 Pro; the physical closed-lid battery test is tracked in MANUAL_TESTING.md and reported there as it is run.
No. A one-time administrator authorization installs a sudo rule scoped to exactly two commands: turn the flag on, turn it off. After that, the app and the CLI never see a password again.
Yes. Every privileged call is Apple's own pmset binary, isolated in a single source
file. No custom code ever runs as root. The full investigation, including rejected approaches, is
public in RESEARCH.md.
A closed laptop in a bag cannot shed heat as well as an open one, and while keep-awake is on, low-battery emergency sleep is disabled too. By default Shutlid switches the battery Energy Mode to Low Power while the lid is closed and restores it when the lid opens, and it logs the battery temperature every five minutes so you can see what happened. Auto-off is on by default (24 hours) as the safety net, adjustable down to 1 hour or off entirely.
Yes. The CLI is the agent interface: shutlid on, shutlid off and
shutlid status, with stable exit codes and no interactive prompts after setup.
caffeinate and sleep assertions stop idle sleep but not the sleep macOS triggers when
the lid closes. A virtual display can fool clamshell mode but still requires AC power and stacks
extra machinery. Shutlid uses the one setting that vetoes lid-close sleep directly, with nothing
else running.
Shutlid is free and open source under the MIT license. The full source, including the research behind it, is on GitHub.
Free, open source, and built to disappear into the background.