Amphetamine

Amphetamine is Kevin's installed macOS keep-awake tool. Use it for visible, human-controlled wake sessions; use the built-in caffeinate utility for scoped terminal and agent-owned commands.

Amphetamine is a Mac App Store utility for preventing a Mac, and optionally its display, from sleeping. It is the right default when Kevin wants a menu-bar control, a visible session state, or a trigger that follows laptop context rather than a single shell command. The App Store listing describes it as a free macOS utility by William Gustafson, with no ads, in-app purchases, tracking, or paid unlocks. Source: App Store, accessed 2026-07-01

The important distinction is ownership. Amphetamine is for the human operating the machine. caffeinate is for a process, script, or agent that can define exactly what it owns and when the wake assertion should end.

What It Does

Amphetamine can start a keep-awake session indefinitely, for a duration, until a clock time, while a file is downloading, or while a specific app is running. During the session it can separately control display sleep, screen saver activation, system sleep while a laptop display is closed, automated cursor movement, and screen locking. Source: App Store, accessed 2026-07-01

Its strongest feature is trigger-based automation. Sessions can start based on external displays, display mirroring, USB or Bluetooth devices, a running or frontmost app, charging state, power adapter state, IP address, Wi-Fi network, Cisco AnyConnect VPN, DNS server, audio output, mounted volume, CPU utilization, or idle threshold. That makes it better than a plain timer when the real invariant is "keep this machine awake while I am in this operating mode." Source: App Store, accessed 2026-07-01

Stack Fit

Kevin has Amphetamine installed on his Mac. Treat it as part of the local productivity stack for long downloads, screen recordings, remote sessions, local model runs, overnight syncs, and anything where changing global macOS sleep settings would be too blunt. Source: User request, 2026-07-01

For agent work, Amphetamine is a supporting tool, not a process-hygiene replacement. If an agent starts a long-running dev server, test watcher, browser, or sync job, it still needs the Agent Process Tracking, Audit, And Cleanup flow: record the process, know the port/PID/PGID, and clean it up when done. Amphetamine prevents accidental sleep; it does not decide whether a process is legitimate.

caffeinate

caffeinate is macOS's built-in command-line utility at /usr/bin/caffeinate. It creates power assertions that alter sleep behavior. With no flags, it prevents idle sleep. When invoked with a utility, the assertion lasts for that utility's execution; otherwise it lasts until caffeinate exits. Source: man caffeinate, macOS, accessed 2026-07-01

Useful shapes:

# Keep the Mac from idle sleeping while a command runs.
caffeinate -i pnpm build

# Keep display, idle sleep, disk idle sleep, and user-active assertion for 1 hour.
caffeinate -dimu -t 3600

# Hold an assertion until an existing process exits.
caffeinate -w "$PID"

Flag model:

Use caffeinate when the wake need is owned by a command. Use Amphetamine when the wake need is owned by Kevin's current working mode.

Decision Rule

Use Amphetamine for human-facing sessions:

• screen recording, demos, uploads, downloads, long reads, or remote access
• trigger sessions tied to Wi-Fi, VPN, external display, power, app state, CPU, or mounted volume
• cases where a visible menu-bar state is useful

Use caffeinate for agent or script sessions:

• one command must not sleep before completion
• an existing PID should keep the system awake until it exits
• the assertion should be automatically released without relying on a human to turn off a menu-bar session

Use neither as a bandage for bad process ownership. If a watcher or server needs to keep running, record it. If it is stale, kill it through Agent Broom or Browser Testing Skills. The right invariant is "the Mac stays awake while useful work is happening," not "the Mac never sleeps because nobody knows what is running."

Risks

Keep-awake tools can drain battery, keep laptops warm, and hide runaway background work. Prefer time-boxed sessions, avoid closed-display behavior unless it is intentional, and let Amphetamine's low-battery/session-ending options work for you instead of fighting macOS forever.

For agent workflows, the safest pattern is command-scoped:

caffeinate -i -- long-running-command

That keeps the machine awake only for the process that justified the assertion. Tiny miracle: the computer stays awake for work, then goes back to being a normal computer. Truly radical.

---

Timeline

• 2026-07-01 | Kevin noted that Amphetamine is installed and asked for a wiki article that also covers the built-in caffeinate utility. Source: User request, 2026-07-01