cc-caffeinated

Keep your Mac awake during Claude Code sessions

Prevents macOS sleep during active Claude Code usage with intelligent activity detection.

Installation

./install.sh

How It Works - "Transcript-Based Activity Detection"

cc-caffeinated monitors Claude's natural activity through transcript files:

• Natural Activity Detection: Every Claude action (user input, tool use, responses) updates the transcript file
• Intelligent Monitoring: Background process periodically checks transcript modification time
• Self-Terminating: Automatically stops after a period of inactivity
• Session Isolation: Each Claude session has its own transcript → its own caffeinate process

Why This Design Works

Traditional approaches:

• Manual control: Requires remembering to start/stop
• Fixed duration: Wake for set time regardless of activity
• Polling: Continuously checks for activity, using resources

cc-caffeinated's approach:

• Transcript-driven: Uses Claude's own activity (file updates) as heartbeat
• Self-monitoring: Each session monitors its own transcript independently
• Minimal overhead: Simple periodic file modification checks
• Fail-safe: Always terminates when transcripts go stale, never leaves system permanently awake

Configuration

Activity Timeout

cc-caffeinated uses configurable activity detection for optimal balance:

• Responsive: Covers typical pauses in Claude conversations
• Efficient: Quickly responds when you step away
• Automatic: No configuration needed - works out of the box

The system monitors transcript file modification time and terminates caffeinate after a period of inactivity. See configuration constants in cc-caffeinate.sh for actual timing values.

Claude Code Hooks Configuration

Add this to your ~/.claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.cc-caffeinated/cc-caffeinate start"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.cc-caffeinated/cc-caffeinate cleanup"
          }
        ]
      }
    ]
  }
}

Note: Manually add these hooks to ~/.claude/settings.json. The installer does not modify settings automatically.

Troubleshooting

Check if running:

ps aux | grep "cc-.*\.json" | grep -v grep
# or use the built-in status checker:
./check-status.sh

Manual cleanup:

pkill -f "cc-.*\.json"
# or stop all caffeinate processes:
pkill caffeinate

Uninstall:

./uninstall.sh

Requirements

• macOS with caffeinate command
• Claude Code with hooks support
• Optional: jq for better JSON parsing