clawdphetamine

Keeps your Mac awake — via Amphetamine — exactly while Claude Code sessions are running.

Long agent runs die quietly when the Mac goes to sleep. clawdphetamine wires Claude Code's SessionStart/SessionEnd hooks to Amphetamine: the first Claude Code session starts a keep-awake session, concurrent sessions are reference-counted, and when the last one ends the Mac is allowed to sleep again. No daemon, no polling — it only runs when a session starts or stops.

Requirements

• macOS with Amphetamine installed and running (free, Mac App Store)
• Claude Code
• Homebrew to install

Install

brew tap olerap/tap https://git.oles.network/olerap/homebrew-tap.git
brew trust olerap/tap
brew install clawdphetamine
clawdphetamine install

clawdphetamine install merges two hooks into ~/.claude/settings.json (idempotently — existing settings are preserved and backed up first):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "/opt/homebrew/bin/clawdphetamine start", "timeout": 20 } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "/opt/homebrew/bin/clawdphetamine stop", "timeout": 20 } ] }
    ]
  }
}

Hooks take effect for sessions started afterwards. The first time a session triggers Amphetamine, macOS may ask for an Automation permission — approve it (see Troubleshooting).

Usage

Normally you never run start/stop yourself — the hooks do. The rest:

command	what it does
clawdphetamine status	tracked sessions, Amphetamine state, hook installation
clawdphetamine reset	clear all tracked sessions; end the owned keep-awake session
clawdphetamine install	add the hooks to ~/.claude/settings.json
clawdphetamine uninstall	remove exactly those hooks again
clawdphetamine start / stop	hook-facing register/deregister (stderr only, always exit 0)

$ clawdphetamine status
clawdphetamine 0.1.0
Amphetamine:      installed: yes, running: yes
Keep-awake:       active (started by clawdphetamine)
Claude sessions:  2
  - 0af1b2c3-...  pid 48112 (claude)  since 2026-07-03T12:01:33+0200
  - 9d8e7f6a-...  pid 49203 (claude)  since 2026-07-03T12:14:02+0200
Hooks:            installed (/Users/you/.claude/settings.json)
Display sleep:    allow
State dir:        /Users/you/.local/state/clawdphetamine

Configuration

Optional config file ~/.config/clawdphetamine/config:

# allow   — Mac stays awake, display may sleep (default)
# prevent — display is kept awake too
# default — defer to Amphetamine's own default-session preferences
display_sleep = allow

The CLAWDPHETAMINE_DISPLAY_SLEEP environment variable overrides the file.

How it works

• Each Claude Code session gets a lock file in ~/.local/state/clawdphetamine/locks/, keyed by the hook's session id and recording the Claude engine's pid. The refcount is simply the number of live locks.
• Every invocation prunes stale locks — pids that no longer exist (crashed or killed sessions) or that were recycled by another process — so a crash can't keep your Mac awake forever: the next hook that fires cleans up.
• clawdphetamine only ends Amphetamine sessions it started (tracked via an ownership marker). If you started a session yourself from the menu bar, it is left alone.

Troubleshooting

macOS Automation permission (the usual suspect). The first osascript call to Amphetamine triggers a consent prompt for the app that runs Claude Code (Terminal, iTerm, the Claude desktop app, …). If it was denied or never answered, clawdphetamine status shows Keep-awake: unknown (osascript failed — check Automation permissions). Fix: System Settings → Privacy & Security → Automation → your terminal app → enable Amphetamine.

Amphetamine isn't running. clawdphetamine warns and does nothing rather than break your session. Open Amphetamine.app and, ideally, add it as a login item (Amphetamine → Preferences → Launch at login).

Mac stays awake although no session is running. clawdphetamine status shows what's tracked; clawdphetamine reset clears all locks and ends an owned keep-awake session.

Hooks don't seem to fire. They apply only to sessions started after clawdphetamine install. Check clawdphetamine status (Hooks: line) and look for the two entries in ~/.claude/settings.json. Claude Code also shows hook errors in its own debug output (claude --debug).

You started your own Amphetamine session and it disappeared. That shouldn't happen — clawdphetamine never ends sessions it didn't start. The one blind spot: if clawdphetamine owns the current session and you replace it manually from the menu bar mid-run, ownership can't be distinguished and the replacement may be ended when the last Claude session exits.

Uninstall

clawdphetamine uninstall   # removes the hooks
clawdphetamine reset       # clears any tracked state
brew uninstall clawdphetamine

Development

brew install shellcheck bats-core librsvg   # dev tools only
make check                                  # shellcheck + bats suites

Single bash script in bin/, tests in test/ (Amphetamine mocked), icon sources in assets/.

License

MIT