Skip to content
Back to search

Insomnia

A macOS menu bar app that safely keeps your MacBook awake with the lid closed, for timed agent sessions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/krishhgg/Insomnia with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/krishhgg/Insomnia'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/krishhgg--insomnia/badge.svg)](/listings/krishhgg--insomnia)

HTML

<a href="/listings/krishhgg--insomnia"><img src="/api/listings/krishhgg--insomnia/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires macOS 26 or later on an Apple Silicon Mac.

Paste this into your coding agent:

Install the latest stable Insomnia release by following https://github.com/krishhgg/Insomnia/blob/main/skills/install-insomnia/SKILL.md. If a step needs my password, give me the command to run in Terminal.

For the newest nightly, write "the newest Insomnia nightly prerelease" in place of "the latest stable Insomnia release". Nightlies are built from `main` on each day it has new commits. They have the newest code and may be broken.

To install a release yourself, follow [docs/install.md](docs/install.md). It covers both channels, how to check the download, and `v0.1.0`, which installs differently. Settings > App shows the installed version, and "Check for updates" there tells you whether a newer release exists without installing anything.

Build from source

Needs Xcode with Swift 6.2 or later. Replace `v<version>` with the latest stable tag, or a nightly tag for the newest code:

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

<details> <summary><strong>What the installer changes on your Mac</strong></summary>

The installer needs your password, because the sudoers rule is a system file. It installs:

- The app, at `~/Applications/Insomnia.app`. - A **recovery agent**, a `launchd` job that runs every minute. If the app is gone when a session should have ended, the agent tries to undo the session's changes. - A **sudoers rule** at `/etc/sudoers.d/insomnia`. A sudoers rule decides who can run what with `sudo`. This one lets your user account, not just Insomnia, run these 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

Any program running as you can use that rule too, so review it before you install. [docs/install.md](docs/install.md#what-gets-installed) lists every file and explains how upgrades replace them.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 336 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/assets/eye-open.svg" alt="Insomnia: an open eye with a round pupil and five lashes above it" width="112">
  3. </p>
  4. <h1 align="center">Insomnia</h1>
  5. <p align="center">
  6. <strong>Keep your Mac awake. Give the session an end time.</strong>
  7. </p>
  8. <p align="center">
  9. A macOS menu bar app for timed awake sessions. Insomnia is an eye icon that
  10. lives in your MacBook menu bar. It has no Dock icon and no main window. Set
  11. how long your Mac stays awake, choose what happens when the lid closes, and
  12. see when something could not be undone.
  13. </p>
  14. <p align="center">
  15. <a href="https://getinsomnia.app"><strong>Website</strong></a> ·
  16. <a href="#install"><strong>Install</strong></a> ·
  17. <a href="#using-it"><strong>Using it</strong></a> ·
  18. <a href="#what-happens-when-the-lid-closes"><strong>Lid close</strong></a> ·
  19. <a href="#how-recovery-works"><strong>Recovery</strong></a> ·
  20. <a href="SECURITY.md"><strong>Security</strong></a>
  21. </p>
  22. <p align="center">
  23. <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/License-MIT-536D78?style=flat-square"></a>
  24. <img alt="macOS 26 or later" src="https://img.shields.io/badge/macOS-26%2B-303336?style=flat-square">
  25. <img alt="Experimental source build" src="https://img.shields.io/badge/Status-experimental-536D78?style=flat-square">
  26. </p>
  27. > **Use a stable, well-ventilated surface, not a closed bag.** Insomnia is
  28. > experimental. Recovery can fail, and a running timer is not a safety
  29. > guarantee.
  30. > [Validation status](docs/release-validation.md) · [Apple's ventilation guidance](https://support.apple.com/en-us/102336)
  31. <p align="center">
  32. <img src="docs/assets/session-flow.svg" alt="Illustrated menu-bar controls: enter Days, Hours, and Minutes, watch the countdown, and hold the end control to finish early. Click the eye or countdown to add time. Closing the lid is optional, and incomplete recovery needs attention." width="880">
  33. </p>
  34. ## Install
  35. Requires macOS 26 or later on an Apple Silicon Mac.
  36. Paste this into your coding agent:
  37. ```text
  38. Install the latest stable Insomnia release by following https://github.com/krishhgg/Insomnia/blob/main/skills/install-insomnia/SKILL.md. If a step needs my password, give me the command to run in Terminal.
  39. ```
  40. For the newest nightly, write "the newest Insomnia nightly prerelease" in
  41. place of "the latest stable Insomnia release". Nightlies are built from `main`
  42. on each day it has new commits. They have the newest code and may be broken.
  43. To install a release yourself, follow [docs/install.md](docs/install.md). It
  44. covers both channels, how to check the download, and `v0.1.0`, which installs
  45. differently. Settings > General shows the installed version, and "Check for
  46. updates" there tells you whether a newer release exists without installing
  47. anything.
  48. ### Build from source
  49. Needs Xcode with Swift 6.2 or later. Replace `v<version>` with the latest
  50. stable tag, or a nightly tag for the newest code:
  51. ```bash
  52. git clone --branch v<version> --depth 1 https://github.com/krishhgg/Insomnia.git
  53. cd Insomnia
  54. ./scripts/install.sh
  55. open "$HOME/Applications/Insomnia.app"
  56. ```
  57. <details>
  58. <summary><strong>What the installer changes on your Mac</strong></summary>
  59. The installer needs your password, because the sudoers rule is a system
  60. file. It installs:
  61. - The app, at `~/Applications/Insomnia.app`.
  62. - A **recovery agent**, a `launchd` job that runs every minute. If the app is
  63. gone when a session should have ended, the agent tries to undo the
  64. session's changes.
  65. - A **sudoers rule** at `/etc/sudoers.d/insomnia`. A sudoers rule decides who
  66. can run what with `sudo`. This one lets your user account, not just
  67. Insomnia, run these four commands without a password:
  68. ```text
  69. /usr/bin/pmset -a disablesleep 1
  70. /usr/bin/pmset -a disablesleep 0
  71. /usr/bin/pmset -b lowpowermode 1
  72. /usr/bin/pmset -b lowpowermode 0
  73. ```
  74. Any program running as you can use that rule too, so review it before you
  75. install. [docs/install.md](docs/install.md#what-gets-installed) lists every
  76. file and explains how upgrades replace them.
  77. </details>
  78. ## Using it
  79. 1. **Start.** Click the eye in the menu bar, enter days, hours and minutes,
  80. and press Enter.
  81. 2. **Add time.** Click the eye or the countdown during a session.
  82. 3. **End early.** Press and hold the end control next to the countdown, or
  83. right-click the menu bar item and choose **End session**.
  84. To show only the eye, turn off "Show the countdown in the menu bar" in
  85. Settings. The eye opens while a session runs and closes when it ends,
  86. and the right-click menu also shows the time left.
  87. 4. **Settings and status.** Right-click the eye. Quit asks Insomnia to undo
  88. the session first, and it refuses while a change is still waiting to be
  89. undone. Saved audio for an output that isn't connected doesn't hold it up.
  90. Insomnia restores that output if it reconnects while the app runs, or at
  91. the next launch.
  92. 5. **Menu bar style.** The Menu bar picker in Settings > General has four
  93. styles. Pills, the default, works as described above. Compact keeps only
  94. the eye in the bar, and a click opens the same pills, countdown and end
  95. ring in a small panel. Minimal is the eye with a ring for the time left:
  96. a click adds the default session length, and a 0.6 s hold ends the
  97. session. Popover shows the eye and, during a session, the time left to
  98. the minute (or the end time). Any click on it, left or right, opens a
  99. popover with time buttons, Custom fields for days, hours and minutes,
  100. the status, Settings and Quit. While a session runs it also has the
  101. ring you hold to end it. Popover style has no right-click menu, since
  102. the popover shows the same things.
  103. 6. **One click.** Turn on "Start a session with one click" in Settings >
  104. General, under the Menu bar picker. Then, in Pills, Compact and Popover,
  105. a click on the eye with no session running starts the default session
  106. length. Option-click opens the usual controls to pick another length,
  107. and in Popover a right-click or Control-click does too. A click during a
  108. session works as it does with the switch off, and never ends the
  109. session. If the start is refused, the pills, the panel or the popover
  110. opens with the reason. Minimal already adds the default length on every
  111. click, so Settings greys the switch out there. It is off by default.
  112. 7. **Sounds.** "Play a sound when you start or end a session" in Settings >
  113. General plays a short tone when you start or end a session from the
  114. menu bar. It is off by default, and while it is off Insomnia makes no
  115. sound and loads none. A session that ends without you asking (the
  116. timer, the recovery agent, Quit, a battery or heat rule, recovery after
  117. a crash) makes no sound. Nothing plays while the displays sleep or the
  118. lid is closed, and `--session` commands make no sound.
  119. 8. **From a script or an agent.** The app's binary drives the running app:
  120. ```bash
  121. INSOMNIA=~/Applications/Insomnia.app/Contents/MacOS/Insomnia
  122. "$INSOMNIA" --session start 7200 # two hours
  123. "$INSOMNIA" --session extend 1800
  124. "$INSOMNIA" --session status
  125. "$INSOMNIA" --session end
  126. ```
  127. It starts, extends and ends the same session the menu bar counts down,
  128. with the same battery and heat rules, and prints one line. It changes
  129. nothing itself, so when the app isn't running it says so and exits 1.
  130. A build without this mode opens the menu bar app instead, so a script
  131. that may meet one checks `InsomniaSessionCommandVersion` in the bundle's
  132. `Info.plist` first.
  133. You don't have to close the lid, and opening it doesn't end the session.
  134. When the timer or a battery or heat rule ends a session with the lid closed,
  135. Insomnia puts the Mac to sleep.
  136. Insomnia stops system sleep, not display sleep, so the display still turns off
  137. when idle. If your Mac then asks for a password, agents that drive the screen
  138. stop at the lock screen. **Keep the screen on and unlocked** in Settings >
  139. General holds the display awake during a session, like `caffeinate -d`, so the
  140. screen saver never starts and the screen never locks while idle. With the lid
  141. closed, the display goes to brightness 0 instead of sleeping. **Lock the
  142. screen** under When the lid closes still locks the screen when you close the
  143. lid. When the session ends or Insomnia quits or crashes, macOS drops the hold,
  144. and the display sleeps and locks as before. Insomnia never changes the lock
  145. setting. The switch is off by default because anyone who opens the Mac during a
  146. session finds it unlocked, unless a lid close locked it.
  147. On battery power, Insomnia turns on Low Power Mode below 40% and ends the
  148. session below 10%. Those are the defaults. You can change both in Settings,
  149. and an end floor of 0 turns the battery end off. The heat rules turn on Low Power
  150. Mode when the Mac gets seriously hot and end the session at critical heat.
  151. They are on by default, and Settings can turn them off. All of these rules
  152. only work while the app runs.
  153. Before your first session, check Settings. Then run a short session you can
  154. watch, and read `~/Library/Logs/Insomnia/insomnia.log` afterward.
  155. ## What happens when the lid closes
  156. <p align="center">
  157. <img src="docs/assets/lid-actions.svg" alt="Illustrated Settings defaults: Slack, WhatsApp, and Discord on the freeze list, Docker's idle rule off, mute on. During a session, lid close applies configured actions; reopening attempts to resume verified owned freezes and restore saved audio. The session continues. Without an active session, lid changes do nothing." width="880">
  158. </p>
  159. During a session, closing the lid does each of these, and opening it tries
  160. to undo them. The timer keeps counting down while the lid is closed.
  161. - **Display and keyboard light go off.** Insomnia saves their brightness
  162. first. With sleep turned off, macOS no longer does this by itself.
  163. - **Apps on the freeze list are frozen.** Freezing sends an app's processes
  164. `SIGSTOP`, which pauses them until `SIGCONT` on lid open. The list starts
  165. with Slack, WhatsApp and Discord. Edit Apps in Settings sets each app to
  166. keep running or to freeze, and "All other apps" keeps running by default.
  167. Set to freeze, it still skips meeting, recording and dictation apps: Zoom,
  168. Teams, Webex, FaceTime, Wispr Flow, Granola, Otter, OBS and Loom.
  169. - **The screen can lock.** Off by default. With "Lock the screen" on in
  170. Settings, closing the lid locks the screen and opening it asks for your
  171. login password. Apps, command-line agents and browser automation keep
  172. running, but agents that work through the screen, such as computer use, wait
  173. until you sign in. Off, the Mac stays signed in with the lid closed. A lid
  174. closed on an external display locks only once the display is unplugged. It
  175. uses a private macOS call, so the menu shows a line if it fails.
  176. - **Audio is muted.** Lid open unmutes each output Insomnia muted, even if you
  177. switched to another one.
  178. - **Low Power Mode turns on.** It turns off when the lid opens, unless a
  179. battery or heat rule still needs it.
  180. - **Docker Desktop is frozen when no container runs.** This one is off by
  181. default.
  182. On Mac laptops with Apple silicon or a T2 chip, closing the lid disconnects
  183. the built-in microphone in hardware. Recording a meeting with the lid closed
  184. needs AirPods or an external mic.
  185. [docs/lid-close.md](docs/lid-close.md) has the details: how Docker is checked,
  186. how brightness is restored, the one-time settings change when you upgrade,
  187. and how to test lid actions without closing the lid.
  188. ## How recovery works
  189. <p align="center">
  190. <img src="docs/assets/recovery-flow.svg" alt="The app and a launchd backstop coordinate through a shared lock and recovery journal. The app handles normal cleanup. The backstop checks every minute and attempts due recovery, leaving valid active sessions alone. Failed or unreadable recovery evidence stays on disk; saved audio needs the app and unconfirmed stopped processes need inspection." width="880">
  191. </p>
  192. Insomnia writes each change to a **recovery journal**, a file on disk, before
  193. it makes the change. Ending the session tries to undo what the journal lists.
  194. If the app crashes or quits, the recovery agent tries the same once the
  195. session's end time has passed.
  196. Some things need you:
  197. - The recovery agent can't restore audio. Open Insomnia again for that.
  198. - The recovery agent doesn't watch the battery or the temperature.
  199. - Insomnia only unfreezes a process it can prove it froze. A frozen process
  200. it can't prove stays frozen until you check it.
  201. If the menu shows a recovery warning, deal with it before you leave the Mac
  202. alone. [docs/recovery.md](docs/recovery.md) explains each case.
  203. ## Optional extras
  204. <details>
  205. <summary><strong>iPhone hotspot handoff and tmux</strong></summary>
  206. If the Wi-Fi drops during a session, Insomnia can join your iPhone's hotspot.
  207. Set System Settings > Wi-Fi > Ask to join hotspots to Automatically, then enter
  208. the hotspot's name and password in Insomnia's Settings. The password stays in
  209. your login Keychain. Insomnia asks for Location Services access, because
  210. macOS requires it to read Wi-Fi network names. It never reads your location.
  211. After you reinstall Insomnia, enter the password again.
  212. After 90 seconds without a network, Insomnia can also type `continue` into a
  213. tmux pane running a coding agent. It only types into panes you list in
  214. Settings and mark yourself:
  215. ```bash
  216. tmux set-option -p -t <session:window.pane> @insomnia-nudge on
  217. ```
  218. It doesn't press Enter unless you turn that on. Mark a pane you don't type in.
  219. [docs/extras.md](docs/extras.md) has the details.
  220. </details>
  221. <details>
  222. <summary><strong>Chrome, Chromium, Arc and Comet throttling</strong></summary>
  223. These browsers slow down windows that macOS reports as hidden, which includes
  224. every window while the lid is closed. If a running browser lacks
  225. `--disable-backgrounding-occluded-windows` or
  226. `--disable-renderer-backgrounding`, the right-click menu (the popover in
  227. Popover style) offers "Relaunch [browser] unthrottled". It asks first,
  228. because relaunching quits the browser, and tabs come back only if the
  229. browser reopens them on startup. Some web apps may still stop with the lid
  230. closed.
  231. [docs/extras.md](docs/extras.md#chrome-chromium-arc-and-comet-throttling) has the
  232. details.
  233. </details>
  234. <details>
  235. <summary><strong>Configuration and privacy</strong></summary>
  236. Settings live in `~/Library/Application Support/Insomnia/config.json` and logs
  237. in `~/Library/Logs/Insomnia/`. Insomnia sets both folders and their files to
  238. owner-only permissions. It leaves symlinks and access control lists (ACLs,
  239. extra per-account permission entries) as they are, so another account can
  240. still have access through one. Logs can contain Wi-Fi names, process details
  241. and tmux targets, so check them before you share one.
  242. [docs/extras.md](docs/extras.md#configuration-and-privacy) has the details.
  243. </details>
  244. ## Uninstall
  245. From your checkout:
  246. ```bash
  247. ./scripts/uninstall.sh # removes the app, the agent and the sudoers rule
  248. ./scripts/uninstall.sh --purge # also removes settings and logs
  249. ```
  250. From an unpacked release zip, run `./uninstall.sh` in its folder instead. The
  251. uninstaller undoes any open session first and stops if it can't.
  252. [docs/install.md](docs/install.md#uninstall) has the details.
  253. ## Development
  254. ```bash
  255. swift build
  256. swift test
  257. ```
  258. The tests use fakes and temporary folders, so they never change your power
  259. settings. See [Contributing](CONTRIBUTING.md), [Security reporting](SECURITY.md),
  260. [Release validation](docs/release-validation.md) and [Design notes](docs/spec.md).
  261. ## Star history
  262. <a href="https://www.star-history.com/?repos=krishhgg%2FInsomnia&amp;type=date&amp;legend=top-left">
  263. <picture>
  264. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=krishhgg/insomnia&amp;type=date&amp;theme=dark&amp;legend=top-left" />
  265. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=krishhgg/insomnia&amp;type=date&amp;legend=top-left" />
  266. <img alt="Star history for krishhgg/Insomnia" src="https://api.star-history.com/svg?repos=krishhgg/insomnia&amp;type=date&amp;legend=top-left" />
  267. </picture>
  268. </a>
  269. ## License
  270. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.