Repository navigation
Awake
Use a stable, well-ventilated surface, not a closed bag. A machine that has been told not to sleep keeps running at full speed with the lid shut, and a laptop in a bag has nowhere to put that heat. Recovery can fail, and a running timer is not a safety guarantee. (Apple's ventilation guidance)
A long Claude Code run is exactly the kind of work a machine naps through: no keyboard, no mouse, nothing on screen moving. Awake holds the machine up while any session is running or waiting on you, and/or for a timer you set, and releases it the moment that stops being true.
The safety design here is adapted from
Insomnia (MIT), a macOS menu-bar app
for timed awake sessions: the recovery journal, the backstop that undoes it
with no app running, the battery and thermal floors, the hard session ceiling,
and reading a disable back because pmset can exit 0 while something else puts
the bit straight back. The design, not the code - every line here is this
project's, and the journal shape, the CLI and the panels are its own.
./install.sh awake # the CLI, the panel section, the recovery backstop
./install.sh awakelid # closed-lid mode as well (EXPERIMENTAL, see below)Both are opt-in and never auto-detected. awake installs claudectl if it is
missing, schedules scripts/awake-backstop.sh every minute (a launchd agent on
macOS, a systemd user timer on Linux, cron as a fallback) and turns the panel
section on. ./install.sh --uninstall awake reverses it, ending any session
first.
claudectl awake on --for 2h # a timer
claudectl awake on --while-sessions # hold while Claude Code is running or waiting
claudectl awake on --for 8h --while-sessions # whichever lasts longer, up to the cap
claudectl awake status # what holds it, until when, what is owed
claudectl awake extend --for 30m # push the deadline out
claudectl awake off # end it and give the machine back
claudectl awake recover --force # undo what a crashed session left behind--for takes 2h, 90m, 1h30m, 1d2h, 45s or a bare number of minutes.
A bare claudectl awake on is an hour: a session with no end is the one thing
this feature must never create.
In the panels: the Awake section has the presets, a While sessions hold,
+30m, Off and - when a past session left something behind - Recover. The
top bar / menu bar shows the countdown while a session is held. Off by default
(awake-enabled / awakeEnabled); ./install.sh awake turns it on.
The MCP awake tool reads the state and can start or stop a session in
conversation ("keep this machine awake while you work on the migration"). It
deliberately cannot switch closed-lid mode on.
The status line can show awake 1:04:12 with --segments=…,awake. It is
silent when nothing is held, and loud (awake? sleepDisabled) when a session
ended without giving a setting back.
A child process, on purpose:
| macOS | caffeinate -i -w <holder pid> |
| Linux | systemd-inhibit --what=idle:sleep --mode=block --who=claude-usage-panel --why=… sleep <n> |
The kernel releases the assertion when that child exits, so a holder that
crashes, is force-quit or is SIGKILLed cannot leave a laptop awake. The Linux
child is bounded by its own sleep, so even an orphan expires on time.
One holder at a time, recorded in session.json with its pid and host. A
second starter sees the live owner and refuses rather than double-holding.
Who the holder is depends on who started the session. claudectl awake on
(and the GNOME dropdown, which runs it) spawns a detached holder of its own;
the macOS app holds its session itself. claudectl awake off therefore signals
only its own holder: a session held by the menu-bar app is ended by dropping
the session file, which the app notices on its next 30-second poll, with the
undo done by the CLI right away. Sending the app a SIGTERM would quit it,
which is not what "end this awake session" should mean.
A session ends on the first of:
- its deadline - every session has one, always;
-
the last Claude Code session going away, for a
--while-sessionshold with no--forof its own (a session parked on a permission prompt still counts: an unanswered prompt is exactly when the machine must not drop off); -
the hard ceiling, 12 hours, measured from now on every extension - so
no chain of
+30mcan walk a laptop through the night; - a battery or thermal floor (below);
-
you, through
claudectl awake off, the panel'sOff, or the MCP tool.
Holding a laptop awake on battery is the one case where this feature can do real harm, so the rules end the session rather than warn about it.
| Reading | What happens |
|---|---|
| Battery below the low-power floor (default 40%) on battery power | Low Power Mode on (macOS) |
| Battery below the end floor (default 10%) on battery power | the session ends |
| A battery that is present but unreadable twice in a row, on battery power | the session ends - a floor cannot be applied to a level nobody can read |
| Thermal state serious | Low Power Mode on |
| Thermal state critical | the session ends |
| Charger connected / back above the floor / cooled down | Low Power Mode off again, if we were the ones who switched it on |
A desktop has no battery and therefore no floor. Setting the end floor to 0 turns the battery end off; the two floors cannot cross (the low-power one is raised out of the way, because the end floor is the one that protects the machine).
Linux has no single "Low Power Mode" to switch, so there the floors end a
session but never change a power mode. The thermal state comes from the hottest
/sys/class/thermal/thermal_zone*/temp (serious at 85 °C, critical at 95 °C -
a heuristic: there is no portable "serious" bit), and on macOS from what the
system itself reports, with pmset -g therm as a fallback.
The floors live in the preferences (GNOME: Integrations ▸ Awake; macOS:
Settings ▸ Sessions ▸ Awake) and are written to
<state dir>/claude-usage-panel/awake/config.json, which is where the holder,
the CLI and the MCP tool read them - so one machine has one set of floors
whichever surface started the session.
Experimental, off by default, and a separate install step. With sleep disabled, closing the lid no longer suspends the machine: it keeps running at full speed, in a space with no airflow, with the display and keyboard backlight left to the OS. Read the warning at the top of this page before you turn it on.
claudectl awake on --for 2h --lid, or the panel's Awake controls while
Keep running with the lid closed is on in the preferences. It is never
implied by a click: turning the section on does not turn lid mode on, and the
MCP tool cannot reach it at all.
./install.sh awakelid writes /etc/sudoers.d/claude-usage-panel-awake,
validated with visudo -c and then proven with sudo -n -l before anything
trusts it. It grants your account exactly four commands and nothing else:
<you> ALL=(root) NOPASSWD: /usr/bin/pmset -a disablesleep 1
<you> ALL=(root) NOPASSWD: /usr/bin/pmset -a disablesleep 0
<you> ALL=(root) NOPASSWD: /usr/bin/pmset -b lowpowermode 1
<you> ALL=(root) NOPASSWD: /usr/bin/pmset -b lowpowermode 0
Every call is sudo -n, which never prompts: without the rule it fails fast
with a readable error instead of hanging a menu bar on a password prompt. The
grant is not exclusive to this project - any process running as your account
can invoke those four commands too. ./install.sh --uninstall awakelid removes
the file, after giving sleep back.
A disable is read back five seconds later. pmset can exit 0 while another
process puts SleepDisabled straight to 0 again (another keep-awake tool doing
exactly that is how Insomnia found a closed lid sleeping a Mac mid-session), so
a lid mode that cannot be proven on is reported as failed rather than trusted.
Nothing privileged at all: a systemd-logind inhibitor,
systemd-inhibit --what=handle-lid-switch --mode=block, taken as your own
user. It needs no root, changes no system file, and goes away with the holder.
polkit allows org.freedesktop.login1.inhibit-handle-lid-switch for a local,
active session by default. If yours refuses it (a hardened policy, or a remote
session), the holder logs lid mode NOT on and the ordinary idle/sleep hold
still works - closing the lid will suspend the machine. Granting it is a policy
decision for your machine; see man 8 systemd-logind and your distribution's
polkit rules.
No logind.conf drop-in is installed. Editing HandleLidSwitch would
change how the lid behaves for every program and every future session, and
would survive a crash of ours; an inhibitor cannot. That trade is not worth
making while the inhibitor works.
Everything above is built so that nothing persistent is changed where that can be avoided. On Linux it never is - both inhibitors are child processes, so the recovery journal there is always clean and every backstop run is a no-op.
macOS closed-lid mode and Low Power Mode are real system settings, so they get the full treatment:
-
The journal is written first. Before
pmsetis run,<state dir>/claude-usage-panel/awake/journal.jsonrecords that the setting is about to be owned, with the session's deadline. - A flag is cleared only after its undo succeeded. A failed undo leaves the claim standing, so the next run retries it.
-
The backstop repairs it with nothing of ours running.
scripts/awake-backstop.shruns every minute and needs no node, no Swift and no panel: it reads the journal, and if the session it belongs to has been over for two minutes, runs the twosudo -n pmsetundos itself. A run that cannot take the lock does nothing and exits 75; the next minute retries. -
Nothing is ever left silently. While a journal is dirty and its session
is over, the GNOME dropdown, the macOS popup and the status line all say so,
with a
Recoverbutton next to it.
The store, <state dir>/claude-usage-panel/awake/ (~/.local/state/... on
Linux, ~/Library/Application Support/... on macOS), all mode 0600 in a 0700
directory. The installer asks claude-code/paths.js for it and passes it to
the backstop as --awake-dir, so the shell never derives it a second time:
| File | What it holds |
|---|---|
session.json |
what is being held, by whom (pid + host), until when |
journal.json |
what the machine owes back |
config.json |
the floors and the ceiling, written by the panels |
.hold.lock |
the mutex the holder and the backstop share around "read, decide, change, write" |
awake.log |
what the holder did, one line per event |
Check it any time (./install.sh awake prints the backstop line with this
machine's store filled in):
scripts/awake-backstop.sh --awake-dir "<the awake store>" --status # what the journal says; changes nothing
claudectl awake status # the same, plus what is holding itclaudectl awake on says "the holder did not start". The detached holder
writes session.json under the lock; if it never appears, its log says why.
cat "$(claudectl awake status --json | grep -o '\.\.\./awake')/awake.log" is
awkward - just look in ~/.local/state/claude-usage-panel/awake/awake.log
(macOS: ~/Library/Application Support/claude-usage-panel/awake/awake.log).
"lid mode NOT on (command-failed): sudo: a password is required". The
sudoers rule is not installed: run ./install.sh awakelid. The ordinary hold
is unaffected.
"lid mode NOT on (reverted)". pmset accepted the change and something put
it back within five seconds. Another keep-awake tool with a root helper is the
usual cause; the session continues without lid mode, which is the honest
outcome.
The machine still slept. An inhibitor blocks idle sleep and the lid, not
a sleep you ask for, a low-battery emergency sleep, or a thermal shutdown. On
Linux, systemd-inhibit --list shows whether the hold is actually registered.
A session ended by itself. claudectl awake status names the reason
(timer, sessions, max-session, battery, battery-unreadable,
thermal, user), and awake.log has the line.