Keep your Mac awake only while Claude Code runs, with hooks

Some newer keep-awake apps advertise that they detect coding agents and keep the Mac up only while one works. Clamshell does not detect agents. You do not need detection, though: Claude Code already announces the start and end of every session to any command you register. This recipe is useful even if you never install Clamshell, and the test notes say exactly what was run and what was not.

First, check you need this at all

On macOS, Claude Code already starts a caffeinate process of its own while it is working. Anthropic's changelog mentions it, and the open GitHub issue anthropics/claude-code #81832 describes it as caffeinate -i -t 300, restarted every four minutes with a short gap each time (both checked October 11, 2026). So:

Which hook events to use

Anthropic's hooks reference (checked October 11, 2026) lists over thirty events. Four matter here:

The tempting design is per turn: arm on UserPromptSubmit, disarm on Stop. It is the wrong default for a closed lid. Once Claude finishes a turn the Mac is free to sleep, and a sleeping, closed MacBook cannot receive your next message from a phone or over SSH. Per session is the safer rule: the Mac stays reachable while a session exists, and sleeps when you end it.

Why two one-line hooks are not enough

You could put open "clamshell://arm" straight into SessionStart and open "clamshell://disarm" into SessionEnd. It works until you run two sessions: close the first and its end hook disarms the Mac while the second is mid-task. /clear has the same problem, since the docs list it as both a SessionEnd reason and a SessionStart source.

The fix is to count. Each session drops a marker file when it starts and removes it when it ends, and the Mac is released only when no markers are left.

The script

Save this as ~/.claude/hooks/agent-awake.sh. It needs nothing beyond what ships with macOS: no jq, no Python.

#!/bin/bash
# agent-awake.sh arm|disarm
# Called by agent hooks. Reads the hook's JSON from stdin.
# Keeps the Mac awake while at least one agent session is open.

BACKEND="${AGENT_AWAKE_BACKEND:-clamshell}"   # clamshell | caffeinate | dryrun
DIR="${TMPDIR:-/tmp}/agent-awake"
mkdir -p "$DIR/sessions"

input="$(cat)"
field() {  # pull one string value out of the hook JSON, no jq needed
  printf '%s' "$input" | sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n 1
}
sid="$(field session_id | tr -cd 'A-Za-z0-9_-')"
reason="$(field reason)"
[ -n "$sid" ] || exit 0

# One hook at a time: mkdir is atomic. Give up waiting after about a second.
tries=0
until mkdir "$DIR/lock" 2>/dev/null; do
  tries=$((tries + 1))
  [ "$tries" -ge 20 ] && break
  sleep 0.05
done
trap 'rmdir "$DIR/lock" 2>/dev/null' EXIT

# A marker per session, holding the agent's process ID ($PPID is the agent).
case "$1" in
  arm)    echo "$PPID" > "$DIR/sessions/$sid" ;;
  disarm) rm -f "$DIR/sessions/$sid" ;;
  *)      exit 0 ;;
esac

# Drop markers whose agent process is gone (crash, kill -9, closed terminal).
count=0
for marker in "$DIR/sessions"/*; do
  [ -e "$marker" ] || continue
  if kill -0 "$(cat "$marker")" 2>/dev/null; then
    count=$((count + 1))
  else
    rm -f "$marker"
  fi
done

keep_awake() {
  case "$BACKEND" in
    clamshell) open "clamshell://arm" ;;
    caffeinate)
      if ! kill -0 "$(cat "$DIR/caffeinate.pid" 2>/dev/null)" 2>/dev/null; then
        nohup caffeinate -i >/dev/null 2>&1 &
        echo $! > "$DIR/caffeinate.pid"
      fi ;;
  esac
}
allow_sleep() {
  case "$BACKEND" in
    clamshell) open "clamshell://disarm" ;;
    caffeinate)
      kill "$(cat "$DIR/caffeinate.pid" 2>/dev/null)" 2>/dev/null
      rm -f "$DIR/caffeinate.pid" ;;
  esac
}

if [ "$1" = arm ]; then
  keep_awake
  echo "$(date '+%F %T') arm    $sid sessions=$count" >> "$DIR/log"
elif [ "$count" -eq 0 ] && [ "$reason" != clear ] && [ "$reason" != resume ]; then
  # /clear and /resume end one session and start the next at once,
  # so the start hook that follows keeps the Mac awake.
  allow_sleep
  echo "$(date '+%F %T') disarm $sid sessions=0" >> "$DIR/log"
else
  echo "$(date '+%F %T') end    $sid sessions=$count (still awake)" >> "$DIR/log"
fi
exit 0

Then make it executable:

mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/agent-awake.sh

Three details are deliberate. The mkdir lock makes hooks take turns, because the docs say matching hooks run in parallel and two sessions can start in the same second. The marker stores $PPID, which in testing was the Claude Code process itself, so a later run can tell a live session from a dead one. And a SessionEnd with reason clear or resume never disarms, because a SessionStart follows.

The Claude Code settings

Per the hooks reference, ~/.claude/settings.json applies to all your projects, .claude/settings.json to one project, and .claude/settings.local.json to one project on your machine only. For a keep-awake rule you want the first. Add this, merging it into any "hooks" object you already have:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/agent-awake.sh arm"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/agent-awake.sh disarm",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

• No matcher. Leaving it out matches every start source and end reason.
• "timeout": 10 on the end hook. SessionEnd hooks get 1.5 seconds by default, and a per-hook timeout raises that. In testing the script took a few hundredths of a second; the margin covers its one-second wait on a stuck lock.
• Workspace trust. In an interactive session, Claude Code holds back hooks from every settings file, your own included, until you accept the trust dialog for the folder.
• Check it loaded. Type /hooks in Claude Code to browse the hooks it has registered.

This uses the default backend, Clamshell. To use caffeinate instead, put the variable in front of both commands:

"command": "AGENT_AWAKE_BACKEND=caffeinate ~/.claude/hooks/agent-awake.sh arm"

With that backend the script starts a single caffeinate -i when the first session opens and kills it when the last one closes, so idle sleep is held off for the whole session, including while Claude waits for you. Issue #81832 reports that the built-in keep-awake lets go about 30 seconds after Claude stops being busy. Neither does anything for a closed lid.

Clamshell keeps a closed MacBook awake with no sudo and no monitor, and takes arm and disarm requests from a hook. Free for 7 days, then $9.99 once.

Download free trial

Apple Silicon, macOS 14+. Notarized by Apple. 3.6 MB. Also on Setapp.

Test it before you trust it

1. Dry run first. Set AGENT_AWAKE_BACKEND=dryrun in both commands. The script then keeps its markers and its log but touches nothing else.
2. Start and end a session. The quickest way is a one-shot run, which fires both hooks:

   claude -p "Reply with the single word ok."
   cat "$TMPDIR/agent-awake/log"

   You should see one arm line and one disarm line with the same session ID.
3. Overlap two sessions. Open Claude Code in two terminals, then quit them one at a time. The first exit logs end ... sessions=1 (still awake); only the second logs disarm.
4. Switch to the real backend. Remove the variable (or set caffeinate). For caffeinate, confirm with pmset -g assertions | grep caffeinate while a session is open. For Clamshell, open its menu and check it shows armed.
5. If nothing happens, start Claude Code with claude --debug-file /tmp/claude.log and read the hook entries in that file.

What happens if a session crashes

If Claude Code dies without running its end hook, its marker stays behind and the Mac stays awake. The script cleans up after it: every time any hook runs, markers whose process ID is no longer alive are deleted before counting. A crashed session is forgotten the next time another session starts or ends.

Tested with Claude Code 2.1.296 on October 11, 2026, by killing a running claude -p session:

• SIGTERM, SIGHUP, SIGINT: the SessionEnd hook still ran and the keep-awake was released. SIGHUP is what a process normally receives when its terminal window closes.
• SIGKILL: no hook ran. The marker and the caffeinate process were left behind, and both were removed by the next session that started and ended.

The gap that remains: if the only session is killed outright and you start no other, nothing runs to clean up. Disarm by hand, from Clamshell's menu or with open "clamshell://disarm", or with pkill caffeinate for the free backend.

The per-turn variant, if you want it

With the lid open and caffeinate, per turn is reasonable: the Mac stays up while Claude works and can idle-sleep while a finished session sits in a forgotten tab. The same script handles it:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "AGENT_AWAKE_BACKEND=caffeinate ~/.claude/hooks/agent-awake.sh arm" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "AGENT_AWAKE_BACKEND=caffeinate ~/.claude/hooks/agent-awake.sh disarm" } ] }
    ],
    "StopFailure": [
      { "hooks": [ { "type": "command", "command": "AGENT_AWAKE_BACKEND=caffeinate ~/.claude/hooks/agent-awake.sh disarm" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "AGENT_AWAKE_BACKEND=caffeinate ~/.claude/hooks/agent-awake.sh disarm", "timeout": 10 } ] }
    ]
  }
}

Know its edges. Stop does not run when you interrupt a turn, so after pressing Esc the Mac stays awake until the next turn finishes or the session ends. StopFailure covers turns that end on an API error. Background work Claude left running after its reply is not protected once Stop has fired.

The Codex variant

Codex has the same pair of events. OpenAI's Codex hooks documentation (checked October 11, 2026) lists SessionStart and SessionEnd, read from ~/.codex/hooks.json or from [hooks] tables in ~/.codex/config.toml, and each command hook receives a JSON object with session_id on standard input. Copy the script to ~/.codex/hooks/agent-awake.sh and add:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "~/.codex/hooks/agent-awake.sh arm" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "~/.codex/hooks/agent-awake.sh disarm", "timeout": 3 } ] }
    ]
  }
}

Three differences from Claude Code, all from OpenAI's page:

• Trust. Codex skips a new or changed hook until you review and trust it. Run /hooks in the Codex CLI after adding these.
• Time limit. SessionEnd hooks get one second by default and three at most, hence "timeout": 3.
• When the end fires. SessionEnd runs when Codex closes normally, when you archive or delete an open conversation, or after a conversation has been idle and not open in any client for 30 minutes.

If both tools see the same $TMPDIR, their markers land in one folder and the sessions count together, so the Mac is released when the last of either ends. The Codex configuration is written from the documentation and has not been run for this page, so test it with the dryrun backend first. If your Codex build has no hooks, or for any other command-line agent, a shell function does the same job for one terminal:

agent-awake() (
  trap 'open "clamshell://disarm"' EXIT
  trap 'exit 130' INT TERM HUP
  open "clamshell://arm"
  "$@"
)

agent-awake codex

The parentheses run it in a subshell, so the EXIT trap sends the disarm request however the agent ends, in both zsh and bash. It does not count sessions: two wrapped agents at once will disarm when the first one exits.

What this recipe does not do

• It follows sessions, not activity. An idle session left open in a tab keeps the Mac awake. Quit sessions you are done with.
• It arms without asking. With the Clamshell backend, any open session means a closed lid no longer sleeps the Mac. Quit your sessions, or check the menu shows inactive, before the Mac goes into a bag.
• Clamshell's own rules still apply. It pauses rather than arming while an external display is connected, and its thermal safety disarms toward normal lid sleep under serious or critical thermal pressure. A hook cannot override either. Clamshell itself has no agent integration; all the logic here is your script.

What was tested for this page

• Run on a Mac, Claude Code 2.1.296, October 11, 2026: the script exactly as printed, loaded from a project-level .claude/settings.json; both events firing in claude -p runs; two real overlapping sessions with the caffeinate backend; ten simulated simultaneous sessions; a stuck lock; the four kill signals; the per-turn settings in one run; the shell function with a stand-in command in zsh and bash.
• From documentation only: the user-level settings location, interactive /clear and /resume (the script's handling was run against simulated input), interrupts and API errors in the per-turn variant, and Codex hooks.
• Clamshell backend: the two open calls use Clamshell's documented URL scheme. Confirm the armed state in the menu on your own Mac.

Frequently asked questions

Related guides

• Keep a MacBook awake with the lid closed
• Keep Claude Code running with the lid closed
• What Claude Code's built-in keep-awake covers, and what it misses
• Why caffeinate does not work with the lid closed
• Keep Codex running when you close your MacBook lid
• Run AI coding agents overnight on a MacBook

Sources checked October 11, 2026: Anthropic's Claude Code hooks reference and changelog, GitHub issue anthropics/claude-code #81832, OpenAI's Codex hooks documentation, and the macOS caffeinate manual page. Hook events change between releases; check Anthropic's current hooks reference before relying on a detail. Read the script before you run it. Clamshell is an independent app, not affiliated with or endorsed by Anthropic or OpenAI. Claude and Claude Code are trademarks of Anthropic.