Caffeinate AI: Keep macOS awake while one or more monitored apps are running (for long agentic sessions with ChatGPT/Codex or Claude)

A developer released caffeinate-ai, a zsh script that keeps macOS from idle-sleeping while monitored applications such as ChatGPT and Codex are running, targeting long agentic coding sessions. The tool polls running apps every five seconds and wraps macOS's built-in caffeinate with -i so the system stays awake while the display can still sleep, and it ships with start, stop, restart, toggle, status, doctor, and run subcommands plus environment-variable configuration for interval, match mode, and target app list.

| | /bin/zsh | | | | | | caffeinate-ai | | | | | | Keep macOS awake while one or more monitored applications are running. | | | | | | Setup: | | | 1. Add to local bin dir: ~/.local/bin/caffeinate-ai | | | 2. Make it executable: chmod +x ~/.local/bin/caffeinate-ai | | | 3. View help and usage: caffeinate-ai --help | | | | | | Defaults: | | | - Monitor ChatGPT/Codex TODO: add Claude | | | - Poll every 5 seconds | | | - Prevent idle system sleep with caffeinate -i | | | - Allow the display to sleep normally | | | - Produce no background logs unless --verbose is supplied | | | | | | Commands: | | | caffeinate-ai --help | | | caffeinate-ai start | | | caffeinate-ai stop | | | caffeinate-ai restart | | | caffeinate-ai toggle | | | caffeinate-ai status | | | caffeinate-ai doctor | | | caffeinate-ai run | | | caffeinate-ai | | | When called without a command, defaults to caffeinate-ai run , | | | which runs caffeinate-ai in the foreground of the current shell. | | | set -u | | | set -o pipefail | | | ----------------------------------------------------------------------------- | | | Constants | | | ----------------------------------------------------------------------------- | | | readonly SCRIPT PATH="${0:A}" | | | readonly SCRIPT NAME="${0:t}" | | | readonly STATE DIR="${HOME}/Library/Caches/caffeinate-ai" | | | readonly PID FILE="${STATE DIR}/caffeinate-ai.pid" | | | readonly LOCK DIR="${STATE DIR}/operation.lock" | | | readonly LOCK PID FILE="${LOCK DIR}/pid" | | | readonly LOG FILE="${STATE DIR}/caffeinate-ai.log" | | | ----------------------------------------------------------------------------- | | | Defaults / environment configuration | | | ----------------------------------------------------------------------------- | | | | | | These defaults can be overridden by environment variables: | | | | | | CAFFEINATE AI INTERVAL=10 | | | CAFFEINATE AI MATCH MODE=exact | | | CAFFEINATE AI APPS='ChatGPT:Codex:Visual Studio Code' | | | CAFFEINATE AI CAFFEINATE ARGS='-i' | | | | | | CLI arguments take precedence over environment configuration. | | | | | | POLL INTERVAL="${CAFFEINATE AI INTERVAL:-5}" | | | MATCH MODE="${CAFFEINATE AI MATCH MODE:-exact}" | | | VERBOSE=false | | | DRY RUN=false | | | | | | Add other applications to monitor here | | | | | | TARGET APPS= | | | "ChatGPT" | | | "Codex" | | | | | | CAFFEINATE ARGS= | | | "-i" | | | | | | if -n "${CAFFEINATE AI APPS:-}" ; then | | | TARGET APPS= | | | "${ @s/:/ CAFFEINATE AI APPS}" | | | | | | fi | | | if -n "${CAFFEINATE AI CAFFEINATE ARGS:-}" ; then | | | CAFFEINATE ARGS= | | | "${ @s/:/ CAFFEINATE AI CAFFEINATE ARGS}" | | | | | | fi | | | | | | PID of the caffeinate process owned by this watcher. | | | | | | CAFFEINATE PID="" | | | | | | Set to 1 only for a detached watcher launched by start . | | | | | | IS DAEMON="${CAFFEINATE AI DAEMON:-0}" | | | ----------------------------------------------------------------------------- | | | Help | | | ----------------------------------------------------------------------------- | | | usage { | | | cat <<EOF | | | Usage: | | | ${SCRIPT NAME} command options | | | Commands: | | | start options | | | Start caffeinate-ai as a detached background watcher. | | | stop | | | Stop the background watcher and its caffeinate child. | | | restart options | | | Stop the current watcher and start a new one. | | | toggle options | | | Stop the watcher if running; otherwise start it. | | | Options are used only when starting. | | | status | | | Show the state of the background watcher and caffeinate child. | | | doctor options | | | Diagnose process detection, watcher state, and the macOS power | | | assertion. | | | run options | | | Run the watcher in the foreground. | | | This is the default when options are supplied without a command. | | | help | | | Show this help message. | | | Options for start, restart, toggle, run, and doctor: | | | -a, --app NAME | | | Add an application/process name to monitor. | | | Supplying --app replaces the default ChatGPT/Codex list. | | | May be specified multiple times: | | | ${SCRIPT NAME} start \\ | | | --app ChatGPT \\ | | | --app Codex | | | -i, --interval SECONDS | | | Poll interval. | | | Default: | | | ${POLL INTERVAL} | | | -m, --match MODE | | | Process matching mode. | | | Supported: | | | exact | | | Exact process-name matching using pgrep -x. | | | contains | | | Match against the full process command using pgrep -f. | | | Default: | | | ${MATCH MODE} | | | -c, --caffeinate ARG | | | Add an argument passed to caffeinate. | | | Supplying this option replaces the default "-i". | | | May be specified multiple times: | | | ${SCRIPT NAME} start \\ | | | --caffeinate=-d \\ | | | --caffeinate=-i | | | -v, --verbose | | | Enable diagnostic output. | | | In background mode, verbose output is written to: | | | ${LOG FILE} | | | The log is truncated each time a new verbose daemon starts. | | | --dry-run | | | Foreground-only mode. | | | Detect applications and report when caffeinate would start or stop, | | | without creating a power assertion. | | | -h, --help | | | Show this help message. | | | Environment variables: | | | CAFFEINATE AI INTERVAL | | | Default polling interval. | | | CAFFEINATE AI MATCH MODE | | | Default matching mode: exact or contains. | | | CAFFEINATE AI APPS | | | Colon-separated default application names. | | | Example: | | | export CAFFEINATE AI APPS='ChatGPT:Codex:Visual Studio Code' | | | CAFFEINATE AI CAFFEINATE ARGS | | | Colon-separated caffeinate arguments. | | | Example: | | | export CAFFEINATE AI CAFFEINATE ARGS='-i' | | | Examples: | | | Start: | | | ${SCRIPT NAME} start | | | Status: | | | ${SCRIPT NAME} status | | | Stop: | | | ${SCRIPT NAME} stop | | | Restart: | | | ${SCRIPT NAME} restart | | | Toggle: | | | ${SCRIPT NAME} toggle | | | Diagnose: | | | ${SCRIPT NAME} doctor | | | Run in the foreground: | | | ${SCRIPT NAME} run | | | Dry-run process detection: | | | ${SCRIPT NAME} run --dry-run | | | Run verbosely: | | | ${SCRIPT NAME} run --verbose | | | Start with verbose background logging: | | | ${SCRIPT NAME} start --verbose | | | Poll every 10 seconds: | | | ${SCRIPT NAME} start --interval 10 | | | Watch only Codex: | | | ${SCRIPT NAME} start --app Codex | | | Watch several applications: | | | ${SCRIPT NAME} start \\ | | | --app ChatGPT \\ | | | --app Codex \\ | | | --app "Visual Studio Code" | | | Prevent both idle system sleep and display sleep: | | | ${SCRIPT NAME} start \\ | | | --caffeinate=-d \\ | | | --caffeinate=-i | | | State: | | | PID: | | | ${PID FILE} | | | Lock: | | | ${LOCK DIR} | | | Verbose log: | | | ${LOG FILE} | | | Exit codes: | | | 0 Success | | | 1 Runtime failure or inactive status | | | 2 Invalid arguments | | | 127 Required command not found | | | EOF | | | } | | | ----------------------------------------------------------------------------- | | | Output | | | ----------------------------------------------------------------------------- | | | print status { | | | print -r -- "$ " | | | } | | | log { | | | if "${VERBOSE}" = true ; then | | | return 0 | | | fi | | | printf ' %s %s\n' \ | | | "$ date '+%Y-%m-%d %H:%M:%S' " \ | | | "$ " | | | } | | | debug { | | | if "${VERBOSE}" == true ; then | | | log "DEBUG: $ " | | | fi | | | } | | | error { | | | printf '%s: error: %s\n' "${SCRIPT NAME}" "$ " &2 | | | } | | | die { | | | local message="$1" | | | local exit code="${2:-1}" | | | error "${message}" | | | exit "${exit code}" | | | } | | | ----------------------------------------------------------------------------- | | | Dependency / input validation | | | ----------------------------------------------------------------------------- | | | require command { | | | local command name="$1" | | | if command -v "${command name}" /dev/null 2 &1; then | | | die "required command not found: ${command name}" 127 | | | fi | | | } | | | validate positive integer { | | | local value="$1" | | | local name="$2" | | | if "${value}" =~ '^ 0-9 +$' ; then | | | die "${name} must be a positive integer; received: ${value}" 2 | | | fi | | | if value < 1 ; then | | | die "${name} must be greater than zero; received: ${value}" 2 | | | fi | | | } | | | validate runtime dependencies { | | | require command caffeinate | | | require command pgrep | | | require command ps | | | require command date | | | require command kill | | | require command sleep | | | require command mkdir | | | require command mv | | | require command rm | | | require command rmdir | | | } | | | validate lifecycle dependencies { | | | require command pgrep | | | require command ps | | | require command kill | | | require command sleep | | | require command mkdir | | | require command rm | | | require command rmdir | | | } | | | validate doctor dependencies { | | | validate lifecycle dependencies | | | require command pmset | | | require command grep | | | } | | | ----------------------------------------------------------------------------- | | | State directory | | | ----------------------------------------------------------------------------- | | | ensure state dir { | | | if mkdir -p "${STATE DIR}"; then | | | die "could not create state directory: ${STATE DIR}" | | | fi | | | } | | | ----------------------------------------------------------------------------- | | | Generic process inspection | | | ----------------------------------------------------------------------------- | | | process is alive { | | | local pid="$1" | | | kill -0 "${pid}" 2 /dev/null | | | } | | | process command { | | | local pid="$1" | | | ps -p "${pid}" -o command= 2 /dev/null | | | } | | | process matches script instance { | | | local pid="$1" | | | if process is alive "${pid}"; then | | | return 1 | | | fi | | | local command line | | | if command line="$ process command "${pid}" "; then | | | return 1 | | | fi | | | if "${command line}" == "${SCRIPT PATH}" \|\| | | | "${command line}" == "${SCRIPT NAME}" ; then | | | return 0 | | | fi | | | return 1 | | | } | | | ----------------------------------------------------------------------------- | | | Atomic operation lock | | | ----------------------------------------------------------------------------- | | | acquire operation lock { | | | validate lifecycle dependencies | | | ensure state dir | | | local attempts=2 | | | while attempts 0 ; do | | | if mkdir "${LOCK DIR}" 2 /dev/null; then | | | if print -r -- "$$" "${LOCK PID FILE}"; then | | | rmdir "${LOCK DIR}" 2 /dev/null \|\| true | | | die "could not write operation lock PID" | | | fi | | | return 0 | | | fi | | | | | | Another process may have created the directory but not yet written the | | | PID file. Give it a brief opportunity to finish. | | | | | | if -f "${LOCK PID FILE}" ; then | | | sleep 0.1 | | | fi | | | local owner pid="" | | | if -f "${LOCK PID FILE}" ; then | | | owner pid="$ <"${LOCK PID FILE}" " | | | fi | | | if "${owner pid}" =~ '^ 0-9 +$' && | | | process matches script instance "${owner pid}"; then | | | die \ | | | "another caffeinate-ai operation is already in progress PID ${owner pid} " | | | fi | | | | | | The lock owner no longer exists or the lock metadata is invalid. | | | | | | rm -f "${LOCK PID FILE}" 2 /dev/null \|\| true | | | if rmdir "${LOCK DIR}" 2 /dev/null; then | | | die "could not recover stale operation lock: ${LOCK DIR}" | | | fi | | | attempts-- | | | done | | | die "could not acquire operation lock" | | | } | | | release operation lock { | | | if -d "${LOCK DIR}" ; then | | | return 0 | | | fi | | | local owner pid="" | | | if -f "${LOCK PID FILE}" ; then | | | owner pid="$ <"${LOCK PID FILE}" " | | | fi | | | | | | Only remove a valid lock owned by this process. | | | | | | if "${owner pid}" = "$$" ; then | | | return 0 | | | fi | | | rm -f "${LOCK PID FILE}" 2 /dev/null \|\| true | | | rmdir "${LOCK DIR}" 2 /dev/null \|\| true | | | } | | | with operation lock { | | | acquire operation lock | | | | | | Ensure an unexpected exit still releases our lock. | | | | | | trap 'release operation lock' EXIT | | | trap 'release operation lock; exit 130' INT | | | trap 'release operation lock; exit 143' TERM | | | trap 'release operation lock; exit 129' HUP | | | "$@" | | | local exit status=$? | | | release operation lock | | | trap - EXIT | | | trap - INT | | | trap - TERM | | | trap - HUP | | | return "${exit status}" | | | } | | | ----------------------------------------------------------------------------- | | | PID file | | | ----------------------------------------------------------------------------- | | | read daemon pid { | | | if -f "${PID FILE}" ; then | | | return 1 | | | fi | | | local pid | | | pid="$ <"${PID FILE}" " | | | if "${pid}" =~ '^ 0-9 +$' ; then | | | debug "invalid PID file; removing ${PID FILE}" | | | rm -f "${PID FILE}" | | | return 1 | | | fi | | | print -r -- "${pid}" | | | } | | | write daemon pid { | | | local pid="$1" | | | local temp file="${PID FILE}.${pid}.tmp" | | | ensure state dir | | | if print -r -- "${pid}" "${temp file}"; then | | | die "could not write temporary PID file: ${temp file}" | | | fi | | | if mv -f "${temp file}" "${PID FILE}"; then | | | rm -f "${temp file}" | | | die "could not write PID file: ${PID FILE}" | | | fi | | | } | | | remove pid file if owned { | | | local expected pid="$1" | | | if -f "${PID FILE}" ; then | | | return 0 | | | fi | | | local pid | | | pid="$ <"${PID FILE}" " | | | if "${pid}" == "${expected pid}" ; then | | | rm -f "${PID FILE}" | | | fi | | | } | | | ----------------------------------------------------------------------------- | | | Daemon validation | | | ----------------------------------------------------------------------------- | | | process matches daemon { | | | local pid="$1" | | | if process matches script instance "${pid}"; then | | | return 1 | | | fi | | | local command line | | | if command line="$ process command "${pid}" "; then | | | return 1 | | | fi | | | | | | A managed daemon is always re-executed using the explicit "run" | | | subcommand. | | | | | | if "${command line}" = " run" ; then | | | return 1 | | | fi | | | return 0 | | | } | | | daemon is running { | | | local pid | | | if pid="$ read daemon pid "; then | | | return 1 | | | fi | | | if process matches daemon "${pid}"; then | | | return 0 | | | fi | | | debug "removing stale PID file for PID ${pid}" | | | rm -f "${PID FILE}" | | | return 1 | | | } | | | ----------------------------------------------------------------------------- | | | Target process detection | | | ----------------------------------------------------------------------------- | | | get matching pids { | | | local process name="$1" | | | local raw pids="" | | | case "${MATCH MODE}" in | | | exact | | | raw pids="$ | | | pgrep \ | | | -U "${UID}" \ | | | -x \ | | | -- "${process name}" \ | | | 2 /dev/null \|\| | | | true | | | " | | | ;; | | | contains | | | raw pids="$ | | | pgrep \ | | | -U "${UID}" \ | | | -f \ | | | -- "${process name}" \ | | | 2 /dev/null \|\| | | | true | | | " | | | ;; | | | | | | return 2 | | | ;; | | | esac | | | if -z "${raw pids}" ; then | | | return 1 | | | fi | | | local pid | | | for pid in ${ f raw pids}; do | | | | | | Do not allow the watcher or its invoking shell to satisfy its own | | | contains-mode query. | | | | | | if "${pid}" == "$$" \|\| "${pid}" == "${PPID}" ; then | | | continue | | | fi | | | print -r -- "${pid}" | | | done | | | } | | | process is running { | | | local process name="$1" | | | local matches | | | matches="$ get matching pids "${process name}" 2 /dev/null \|\| true " | | | -n "${matches}" | | | } | | | find running target { | | | local app | | | for app in "${TARGET APPS @ }"; do | | | if process is running "${app}"; then | | | print -r -- "${app}" | | | return 0 | | | fi | | | done | | | return 1 | | | } | | | ----------------------------------------------------------------------------- | | | caffeinate lifecycle | | | ----------------------------------------------------------------------------- | | | caffeinate is running { | | | if -z "${CAFFEINATE PID}" ; then | | | return 1 | | | fi | | | process is alive "${CAFFEINATE PID}" | | | } | | | start caffeinate { | | | if caffeinate is running; then | | | debug "caffeinate already running as PID ${CAFFEINATE PID}" | | | return 0 | | | fi | | | CAFFEINATE PID="" | | | debug "starting: caffeinate ${ j: : CAFFEINATE ARGS}" | | | caffeinate "${CAFFEINATE ARGS @ }" & | | | local pid=$ | | | | | | Give caffeinate a short opportunity to reject invalid arguments. | | | | | | sleep 0.1 | | | if process is alive "${pid}"; then | | | wait "${pid}" 2 /dev/null | | | local exit status=$? | | | error "caffeinate failed to start exit status ${exit status} " | | | return 1 | | | fi | | | CAFFEINATE PID="${pid}" | | | log "Started caffeinate PID ${CAFFEINATE PID} " | | | return 0 | | | } | | | stop caffeinate { | | | if -z "${CAFFEINATE PID}" ; then | | | return 0 | | | fi | | | local pid="${CAFFEINATE PID}" | | | | | | Clear state immediately so cleanup remains idempotent. | | | | | | CAFFEINATE PID="" | | | if process is alive "${pid}"; then | | | debug "caffeinate PID ${pid} is no longer running" | | | wait "${pid}" 2 /dev/null \|\| true | | | return 0 | | | fi | | | debug "sending TERM to caffeinate PID ${pid}" | | | if kill -TERM "${pid}" 2 /dev/null; then | | | error "could not terminate caffeinate PID ${pid}" | | | return 1 | | | fi | | | wait "${pid}" 2 /dev/null \|\| true | | | log "Stopped caffeinate" | | | return 0 | | | } | | | ----------------------------------------------------------------------------- | | | Watcher cleanup / signals | | | ----------------------------------------------------------------------------- | | | cleanup watcher { | | | local original status=$? | | | debug "cleaning up" | | | stop caffeinate \|\| true | | | if "${IS DAEMON}" == "1" ; then | | | remove pid file if owned "$$" | | | fi | | | return "${original status}" | | | } | | | handle signal { | | | local signal name="$1" | | | local exit code=1 | | | case "${signal name}" in | | | INT | | | exit code=130 | | | ;; | | | TERM | | | exit code=143 | | | ;; | | | HUP | | | exit code=129 | | | ;; | | | esac | | | log "Received ${signal name}; shutting down" | | | exit "${exit code}" | | | } | | | ----------------------------------------------------------------------------- | | | Argument parsing | | | ----------------------------------------------------------------------------- | | | parse run arguments { | | | local custom apps=false | | | local custom caffeinate args=false | | | while $ 0 ; do | | | case "$1" in | | | -a\|--app | | | if $ < 2 ; then | | | die "$1 requires an application/process name" 2 | | | fi | | | if "${custom apps}" == false ; then | | | TARGET APPS= | | | custom apps=true | | | fi | | | TARGET APPS+= "$2" | | | shift 2 | | | ;; | | | --app= | | | if "${custom apps}" == false ; then | | | TARGET APPS= | | | custom apps=true | | | fi | | | TARGET APPS+= "${1 =}" | | | shift | | | ;; | | | -i\|--interval | | | if $ < 2 ; then | | | die "$1 requires a number of seconds" 2 | | | fi | | | POLL INTERVAL="$2" | | | shift 2 | | | ;; | | | --interval= | | | POLL INTERVAL="${1 =}" | | | shift | | | ;; | | | -m\|--match | | | if $ < 2 ; then | | | die "$1 requires either 'exact' or 'contains'" 2 | | | fi | | | MATCH MODE="$2" | | | shift 2 | | | ;; | | | --match= | | | MATCH MODE="${1 =}" | | | shift | | | ;; | | | -c\|--caffeinate | | | if $ < 2 ; then | | | die "$1 requires a caffeinate argument" 2 | | | fi | | | if "${custom caffeinate args}" == false ; then | | | CAFFEINATE ARGS= | | | custom caffeinate args=true | | | fi | | | CAFFEINATE ARGS+= "$2" | | | shift 2 | | | ;; | | | --caffeinate= | | | if "${custom caffeinate args}" == false ; then | | | CAFFEINATE ARGS= | | | custom caffeinate args=true | | | fi | | | CAFFEINATE ARGS+= "${1 =}" | | | shift | | | ;; | | | -v\|--verbose | | | VERBOSE=true | | | shift | | | ;; | | | --dry-run | | | DRY RUN=true | | | shift | | | ;; | | | -h\|--help | | | usage | | | exit 0 | | | ;; | | | -- | | | shift | | | break | | | ;; | | | - | | | die "unknown option: $1" 2 | | | ;; | | | | | | die "unexpected argument: $1" 2 | | | ;; | | | esac | | | done | | | validate positive integer "${POLL INTERVAL}" "poll interval" | | | case "${MATCH MODE}" in | | | exact\|contains | | | ;; | | | | | | die \ | | | "match mode must be 'exact' or 'contains'; received: ${MATCH MODE}" \ | | | 2 | | | ;; | | | esac | | | if ${ TARGET APPS @ } == 0 ; then | | | die "at least one application/process must be specified" 2 | | | fi | | | local app | | | for app in "${TARGET APPS @ }"; do | | | if -z "${app}" ; then | | | die "application/process names may not be empty" 2 | | | fi | | | done | | | if ${ CAFFEINATE ARGS @ } == 0 ; then | | | die "at least one caffeinate argument must be specified" 2 | | | fi | | | local caffeinate arg | | | for caffeinate arg in "${CAFFEINATE ARGS @ }"; do | | | if -z "${caffeinate arg}" ; then | | | die "caffeinate arguments may not be empty" 2 | | | fi | | | done | | | } | | | ----------------------------------------------------------------------------- | | | Foreground watcher | | | ----------------------------------------------------------------------------- | | | run monitor { | | | parse run arguments "$@" | | | validate runtime dependencies | | | trap cleanup watcher EXIT | | | trap 'handle signal INT' INT | | | trap 'handle signal TERM' TERM | | | trap 'handle signal HUP' HUP | | | if "${IS DAEMON}" == "1" ; then | | | write daemon pid "$$" | | | fi | | | log "Watching for: ${ j:, : TARGET APPS}" | | | log "Poll interval: ${POLL INTERVAL}s" | | | log "Process matching: ${MATCH MODE}" | | | log "Caffeinate arguments: ${ j: : CAFFEINATE ARGS}" | | | if "${DRY RUN}" == true ; then | | | print status "Dry-run mode enabled" | | | fi | | | local previous target="" | | | while true; do | | | local running target="" | | | if running target="$ find running target "; then | | | debug "detected target process: ${running target}" | | | if "${running target}" = "${previous target}" ; then | | | if "${DRY RUN}" == true ; then | | | print status \ | | | "Dry run: would start caffeinate for ${running target}" | | | else | | | log "Detected ${running target}" | | | fi | | | previous target="${running target}" | | | fi | | | if "${DRY RUN}" = true ; then | | | if caffeinate is running; then | | | | | | If a PID was recorded but is no longer alive, caffeinate died | | | unexpectedly rather than being intentionally stopped. | | | | | | if -n "${CAFFEINATE PID}" ; then | | | log \ | | | "caffeinate exited unexpectedly; restarting" | | | fi | | | if start caffeinate; then | | | error \ | | | "will retry caffeinate on the next polling cycle" | | | fi | | | fi | | | fi | | | else | | | if -n "${previous target}" ; then | | | if "${DRY RUN}" == true ; then | | | print status "Dry run: would stop caffeinate" | | | else | | | log "No monitored applications are running" | | | fi | | | previous target="" | | | fi | | | if "${DRY RUN}" = true ; then | | | if caffeinate is running; then | | | stop caffeinate \|\| true | | | elif -n "${CAFFEINATE PID}" ; then | | | debug \ | | | "clearing stale caffeinate PID ${CAFFEINATE PID}" | | | CAFFEINATE PID="" | | | fi | | | fi | | | fi | | | sleep "${POLL INTERVAL}" | | | done | | | } | | | ----------------------------------------------------------------------------- | | | Child argument construction | | | ----------------------------------------------------------------------------- | | | build child arguments { | | | local app | | | for app in "${TARGET APPS @ }"; do | | | print -r -- "--app" | | | print -r -- "${app}" | | | done | | | print -r -- "--interval" | | | print -r -- "${POLL INTERVAL}" | | | print -r -- "--match" | | | print -r -- "${MATCH MODE}" | | | local caffeinate arg | | | for caffeinate arg in "${CAFFEINATE ARGS @ }"; do | | | print -r -- "--caffeinate=${caffeinate arg}" | | | done | | | if "${VERBOSE}" == true ; then | | | print -r -- "--verbose" | | | fi | | | } | | | ----------------------------------------------------------------------------- | | | Background daemon start | | | ----------------------------------------------------------------------------- | | | start daemon current config { | | | validate runtime dependencies | | | require command nohup | | | if "${DRY RUN}" == true ; then | | | die "--dry-run is only supported with the run command" 2 | | | fi | | | ensure state dir | | | local existing pid | | | if daemon is running; then | | | existing pid="$ read daemon pid " | | | print status \ | | | "caffeinate-ai is already running PID ${existing pid} " | | | return 0 | | | fi | | | rm -f "${PID FILE}" | | | local child args= | | | "${ @f $ build child arguments }" | | | | | | debug "starting detached watcher" | | | | | | Verbose logs are deliberately session-scoped rather than append-only. | | | | | | if "${VERBOSE}" == true ; then | | | if : "${LOG FILE}"; then | | | die "could not initialize verbose log: ${LOG FILE}" | | | fi | | | CAFFEINATE AI DAEMON=1 \ | | | nohup "${SCRIPT PATH}" run "${child args @ }" \ | | | "${LOG FILE}" \ | | | 2 &1 \ | | | </dev/null & | | | else | | | CAFFEINATE AI DAEMON=1 \ | | | nohup "${SCRIPT PATH}" run "${child args @ }" \ | | | /dev/null \ | | | 2 &1 \ | | | </dev/null & | | | fi | | | local pid=$ | | | | | | Wait for the child to finish initialization and write its PID file. | | | | | | local attempts=30 | | | local daemon pid="" | | | while attempts 0 ; do | | | if process is alive "${pid}"; then | | | error "caffeinate-ai failed to start" | | | if "${VERBOSE}" == true ; then | | | error "check log: ${LOG FILE}" | | | fi | | | return 1 | | | fi | | | if daemon pid="$ read daemon pid 2 /dev/null "; then | | | if "${daemon pid}" == "${pid}" && | | | process matches daemon "${pid}"; then | | | print status \ | | | "Started caffeinate-ai PID ${pid} " | | | if "${VERBOSE}" == true ; then | | | print status \ | | | "Verbose log: ${LOG FILE}" | | | fi | | | return 0 | | | fi | | | fi | | | sleep 0.1 | | | attempts-- | | | done | | | | | | Never intentionally leave an unmanageable daemon behind. | | | | | | if process matches daemon "${pid}"; then | | | kill -TERM "${pid}" 2 /dev/null \|\| true | | | fi | | | rm -f "${PID FILE}" | | | error "timed out waiting for caffeinate-ai to initialize" | | | if "${VERBOSE}" == true ; then | | | error "check log: ${LOG FILE}" | | | fi | | | return 1 | | | } | | | ----------------------------------------------------------------------------- | | | Background daemon stop | | | ----------------------------------------------------------------------------- | | | stop daemon current { | | | validate lifecycle dependencies | | | local pid | | | if daemon is running; then | | | rm -f "${PID FILE}" | | | print status \ | | | "caffeinate-ai background watcher is not running" | | | return 0 | | | fi | | | pid="$ read daemon pid " | | | print status \ | | | "Stopping caffeinate-ai PID ${pid} " | | | if kill -TERM "${pid}" 2 /dev/null; then | | | error "could not send TERM to PID ${pid}" | | | return 1 | | | fi | | | | | | Allow roughly five seconds for graceful shutdown. | | | | | | local attempts=50 | | | while attempts 0 ; do | | | if process matches daemon "${pid}"; then | | | break | | | fi | | | sleep 0.1 | | | attempts-- | | | done | | | if process matches daemon "${pid}"; then | | | error \ | | | "process did not stop gracefully; sending SIGKILL" | | | kill -KILL "${pid}" 2 /dev/null \|\| true | | | attempts=20 | | | while attempts 0 ; do | | | if process matches daemon "${pid}"; then | | | break | | | fi | | | sleep 0.1 | | | attempts-- | | | done | | | fi | | | if process matches daemon "${pid}"; then | | | error "could not stop caffeinate-ai PID ${pid}" | | | return 1 | | | fi | | | remove pid file if owned "${pid}" | | | print status "Stopped caffeinate-ai" | | | return 0 | | | } | | | ----------------------------------------------------------------------------- | | | Restart / toggle | | | ----------------------------------------------------------------------------- | | | restart daemon current config { | | | stop daemon current \|\| return $? | | | start daemon current config | | | } | | | toggle daemon current config { | | | if daemon is running; then | | | stop daemon current | | | else | | | start daemon current config | | | fi | | | } | | | ----------------------------------------------------------------------------- | | | caffeinate child lookup | | | ----------------------------------------------------------------------------- | | | get caffeinate child pids { | | | local daemon pid="$1" | | | pgrep \ | | | -U "${UID}" \ | | | -P "${daemon pid}" \ | | | -x \ | | | caffeinate \ | | | 2 /dev/null \|\| | | | true | | | } | | | get first caffeinate child pid { | | | local daemon pid="$1" | | | local raw pids | | | raw pids="$ get caffeinate child pids "${daemon pid}" " | | | if -z "${raw pids}" ; then | | | return 1 | | | fi | | | local pids= | | | "${ @f raw pids}" | | | | | | if ${ pids @ } == 0 ; then | | | return 1 | | | fi | | | print -r -- "${pids 1 }" | | | } | | | ----------------------------------------------------------------------------- | | | Status | | | ----------------------------------------------------------------------------- | | | status daemon { | | | validate lifecycle dependencies | | | local pid | | | if daemon is running; then | | | rm -f "${PID FILE}" | | | print status \ | | | "caffeinate-ai background watcher is not running" | | | return 1 | | | fi | | | pid="$ read daemon pid " | | | print status \ | | | "caffeinate-ai background watcher is running PID ${pid} " | | | local caffeinate pid="" | | | if caffeinate pid="$ | | | get first caffeinate child pid "${pid}" | | | "; then | | | print status \ | | | "caffeinate is active PID ${caffeinate pid} " | | | else | | | print status \ | | | "caffeinate is currently inactive" | | | fi | | | return 0 | | | } | | | ----------------------------------------------------------------------------- | | | Doctor | | | ----------------------------------------------------------------------------- | | | doctor { | | | parse run arguments "$@" | | | validate doctor dependencies | | | if "${DRY RUN}" == true ; then | | | die "--dry-run is only supported with the run command" 2 | | | fi | | | print status "caffeinate-ai diagnostics" | | | print status "" | | | | | | Watcher | | | | | | print status "Watcher:" | | | local daemon pid="" | | | if daemon is running; then | | | daemon pid="$ read daemon pid " | | | print status \ | | | " background: running PID ${daemon pid} " | | | else | | | print status \ | | | " background: not running" | | | fi | | | print status "" | | | | | | Targets | | | | | | print status "Targets:" | | | local app | | | local raw pids | | | for app in "${TARGET APPS @ }"; do | | | raw pids="$ get matching pids "${app}" 2 /dev/null \|\| true " | | | if -n "${raw pids}" ; then | | | local pids= | | | "${ @f raw pids}" | | | | | | print status \ | | | " ${app}: running PIDs ${ j:, : pids} " | | | else | | | print status \ | | | " ${app}: not running" | | | fi | | | done | | | print status "" | | | | | | caffeinate | | | | | | print status "Sleep prevention:" | | | local caffeinate pid="" | | | if -n "${daemon pid}" && | | | caffeinate pid="$ | | | get first caffeinate child pid "${daemon pid}" | | | "; then | | | print status \ | | | " caffeinate: active PID ${caffeinate pid} " | | | local assertions | | | assertions="$ pmset -g assertions 2 /dev/null \|\| true " | | | if print -r -- "${assertions}" \| | | | grep -E \ | | | "pid :space: +${caffeinate pid}\\ " \ | | | /dev/null 2 &1; then | | | print status \ | | | " power assertion: present" | | | else | | | print status \ | | | " power assertion: not detected" | | | fi | | | else | | | print status \ | | | " caffeinate: inactive" | | | print status \ | | | " power assertion: none expected" | | | fi | | | print status "" | | | | | | Effective diagnostic configuration | | | | | | print status "Configuration:" | | | print status \ | | | " interval: ${POLL INTERVAL}s" | | | print status \ | | | " match: ${MATCH MODE}" | | | print status \ | | | " apps: ${ j:, : TARGET APPS}" | | | print status \ | | | " caffeinate arguments: ${ j: : CAFFEINATE ARGS}" | | | return 0 | | | } | | | ----------------------------------------------------------------------------- | | | Background configuration preparation | | | ----------------------------------------------------------------------------- | | | prepare background configuration { | | | parse run arguments "$@" | | | if "${DRY RUN}" == true ; then | | | die "--dry-run is only supported with the run command" 2 | | | fi | | | validate runtime dependencies | | | require command nohup | | | } | | | ----------------------------------------------------------------------------- | | | Main | | | ----------------------------------------------------------------------------- | | | main { | | | local subcommand="${1:-run}" | | | case "${subcommand}" in | | | start | | | shift | | | prepare background configuration "$@" | | | with operation lock \ | | | start daemon current config | | | ;; | | | stop | | | shift | | | if $ 0 ; then | | | die "stop does not accept additional arguments" 2 | | | fi | | | validate lifecycle dependencies | | | with operation lock \ | | | stop daemon current | | | ;; | | | restart | | | shift | | | | | | Validate everything before stopping an existing daemon. That prevents | | | an invalid replacement configuration from unnecessarily taking down | | | a working watcher. | | | | | | prepare background configuration "$@" | | | with operation lock \ | | | restart daemon current config | | | ;; | | | toggle | | | shift | | | prepare background configuration "$@" | | | with operation lock \ | | | toggle daemon current config | | | ;; | | | status | | | shift | | | if $ 0 ; then | | | die "status does not accept additional arguments" 2 | | | fi | | | status daemon | | | ;; | | | doctor | | | shift | | | doctor "$@" | | | ;; | | | run | | | "run" may be implicit when no arguments were supplied. | | | if $ 0 ; then | | | shift | | | fi | | | run monitor "$@" | | | ;; | | | help | | | usage | | | ;; | | | -h\|--help | | | usage | | | ;; | | | - | | | | | | Shorthand: | | | | | | caffeinate-ai --verbose | | | | | | is equivalent to: | | | | | | caffeinate-ai run --verbose | | | | | | run monitor "$@" | | | ;; | | | | | | error "unknown command: ${subcommand}" | | | print &2 | | | usage &2 | | | exit 2 | | | ;; | | | esac | | | } | | | main "$@" |