Insomnia, a menu bar timer that ends a closed-lid Mac session

An eye icon in the menu bar, with a timer attached

Insomnia is described as a macOS menu bar app for timed awake sessions. It is an eye icon that lives in your MacBook menu bar, with no Dock icon and no main window. The tagline is that it keeps your Mac awake and gives the session an end time.

That framing is the whole difference from the tools it sits next to. The repository topics name Amphetamine as the alternative and caffeinate as the mechanism, and the way Insomnia differs is that the session is bounded. A keep-awake tool that runs until you stop it is fine for a video call and wrong for an unattended agent run, because the failure mode of a still-awake Mac is a machine that never goes to sleep and a battery that never charges.

The topics also list the tools it is meant to work alongside, claude-code and codex, and the general category of ai-agents. That is the use case in one line: a long agent session, on a closed lid, with a defined end.

The interface is four steps. You click the eye in the menu bar, enter days, hours and minutes, and press Enter to start. During a session you click the eye or the countdown to add time. You press and hold the end control next to the countdown to finish early. And you right-click the eye for settings and status.

The hold gesture for ending is a deliberate design choice rather than a misclick risk. A button that undoes a whole session and restores your machine deserves friction, and a press-and-hold is the cheapest way to add it.

The app is a Swift project with Package.swift at the root, Sources/, Resources/, Tests/, docs/, scripts/ and skills/ directories, and a.greptile/ directory for automated code review. The licence is MIT, the homepage is getinsomnia.app, and the last push was on 2026-10-18. The releases are nightlies named by date and commit, so nightly-20261013-b6a7499c183b, and the README says nightlies are built from main on each day it has new commits.

What the lid close actually does, and what it undoes

During a session, closing the lid applies a set of actions, and opening it tries to undo them. The timer keeps counting down the whole time the lid is closed, so the session does not pause because the machine is shut.

The first action is that display and keyboard light go off. Insomnia saves their brightness first, and the README notes that with sleep turned off macOS no longer does this by itself, which is a detail that explains why the app has to handle it.

The second is that apps on the freeze list are frozen. Freezing sends an app's processes SIGSTOP, which pauses them until SIGCONT on lid open. The list starts with Slack, WhatsApp and Discord, which is a sensible default for the stated use case: a machine sitting in a bag or on a desk with the lid shut should not post notifications. There is a freeze every other app option, off by default, and even when it is on it skips a list of apps you would not want to pause. The skipped ones are Zoom, Teams, Webex, FaceTime, Wispr Flow, Granola, Otter, OBS and Loom, which is a list of meeting, recording and dictation apps. A freeze that suspended a recording tool would corrupt the recording rather than protect it.

The third action is that audio is muted, and lid open unmutes each output Insomnia muted, even if you switched to another one. That last clause is the interesting one, because it means the app tracks which outputs it silenced rather than just tracking a global mute state, so a later unmute does not leave a different output muted forever.

The fourth is that Low Power Mode turns on, and it turns off when the lid opens unless a battery or heat rule still needs it. The fifth is that Docker Desktop is frozen when no container runs, which is off by default.

One hardware caveat is stated plainly. On Mac laptops with Apple silicon or a T2 chip, closing the lid disconnects the built-in microphone in hardware, so recording a meeting with the lid closed needs AirPods or an external mic. That is a hardware behaviour the app cannot work around, and it is the kind of thing that would otherwise be discovered during a meeting.

The installer writes a sudoers rule, and you should read it

The installation section has a details block titled what the installer changes on your Mac, and its content is the most important thing to understand before running it.

The installer needs your password, because the sudoers rule is a system file. It installs three things. The app goes to ~/Applications/Insomnia.app, which keeps it out of the system Applications folder and out of the way of a normal update. A recovery agent is a launchd job that runs every minute, and its purpose is that if the app is gone when a session should have ended, the agent tries to undo the session's changes. And a sudoers rule is installed at /etc/sudoers.d/insomnia.

The rule decides who can run what with sudo, and this one lets your user account, not just Insomnia, run four commands without a password:

/usr/bin/pmset -a disablesleep 1
/usr/bin/pmset -a disablesleep 0
/usr/bin/pmset -b lowpowermode 1
/usr/bin/pmset -b lowpowermode 0

Those four commands are the entire mechanism. disablesleep 1 and 0 turn the system sleep override on and off, and lowpowermode 1 and 0 do the same for Low Power Mode on battery power. Nothing here is Insomnia specific, which is exactly why the rule cannot be scoped to Insomnia, and the README says so: any program running as you can use that rule too, so review it before you install. The documentation at docs/install.md lists every file and explains how upgrades replace them.

The install route itself is unusual. The README asks you to paste a prompt into your coding agent, and the prompt points at a skill document at skills/install-insomnia/SKILL.md in the repository, with the instruction that if a step needs the password you should be given the command to run in Terminal. So the intended flow is that the agent does the mechanical steps and hands you the one privileged command rather than asking for your password in a chat window.

Building from source needs Xcode with Swift 6.2 or later, and the commands are a shallow clone of a tag followed by the install script:

git clone --branch v<version> --depth 1 https://github.com/krishhgg/Insomnia.git
cd Insomnia
./scripts/install.sh
open "$HOME/Applications/Insomnia.app"

Note that the shallow clone and the explicit tag are there so you build the version you intended, and the version v0.1.0 installs differently, which the install documentation covers.

Battery and heat rules, and the limits of a running timer

There are rules that override your requested duration, and they are worth understanding because they are the difference between a session that ends and a session that runs until the machine dies.

On battery power, Insomnia turns on Low Power Mode below 40% and ends the session below 10%. Those are the defaults, both are changeable in Settings, and an end floor of 0 turns the battery end off. The heat rules work the same way, turning on Low Power Mode when the Mac gets seriously hot and ending the session at critical heat, and they are on by default with a Settings switch to turn them off.

Then there is the sentence that matters most: all of these rules only work while the app runs. That is the same boundary as the recovery mechanism. If the app is not running, the timer is not running, the battery rules are not running and the heat rules are not running. A crash, a force quit or a logout during a session takes all of it with it.

That is exactly why the recovery agent exists as a separate launchd job that runs every minute, because it is the only component that survives the app, and it is the component that undoes a session whose end the app never got to perform.

The quit behaviour is consistent with that design. Right-clicking the eye gives you a Quit, and the README says Quit asks Insomnia to undo the session first, and it refuses while a change is still waiting to be undone. One exception is that saved audio for an output that is not connected does not hold it up, because Insomnia restores that output if it reconnects while the app runs, or at the next launch. So the app distinguishes between a change it must undo before it can exit and one it can defer.

The advice for a first run is sensible and specific. Before your first session, check Settings. Then run a short session you can watch, and read ~/Library/Logs/Insomnia/insomnia.log afterward. The log is the difference between trusting the tool and checking it.

What the project calls experimental, and what it is honest about

The status badge in the README header reads experimental, and the warning block at the top of the page is the clearest statement of the risk:

Use a stable, well-ventilated surface, not a closed bag. Insomnia is experimental. Recovery can fail, and a running timer is not a safety guarantee. The block links to the validation status at docs/release-validation.md and to Apple's ventilation guidance.

A closed bag with a MacBook running a long job is a heat problem, and the project says so rather than implying the timer protects you. A running timer is not a safety guarantee, because a timer keeps the machine awake and awake means heat.

The other honesty in the project is the release validation document, which is linked from the warning. The nightly channel is described plainly: nightlies are built from main on each day it has new commits, they have the newest code, and they may be broken. That is a direct statement that the nightly channel is not a stable channel, and the recent release names support it, with three nightlies on consecutive days in October 2026.

The security documentation is a file in the repository root, SECURITY.md, and the README links to it in its own navigation. Given that the app installs a passwordless sudoers rule and a launchd agent that runs as your user, having a SECURITY.md that explains the trust model is not a formality.

The result is a project that tells you what it cannot promise. It cannot promise the recovery will work, it cannot promise the timer protects the hardware, it cannot promise the nightlies are sound, and it tells you to review a sudoers rule that any program running as you can use. For a tool that keeps a machine awake unattended, that candour is worth more than a longer feature list.

Editorial conclusion

Insomnia suits someone who runs a long agent session on a MacBook with the lid closed and needs the machine to stay awake, to stay quiet and to stop on its own rather than when you remember. It is the wrong tool if you want a general keep-awake utility, since it is scoped to timed sessions with an explicit end and a recovery step, and it is the wrong tool if you will not accept a background agent and a passwordless sudo rule on your account, since that is how the session is undone when the app is gone. Before installing, read the section on what the installer changes, since the sudoers rule lets your user account run four pmset commands without a password, and treat the recovery mechanism as unproven, because the project labels itself experimental and states that recovery can fail.

Frequently asked questions

Official sources

1. krishhgg/Insomnia on GitHub
2. License: MIT
3. Project website
4. README
5. Releases