diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 55547f5..e9578fe 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -328,6 +328,17 @@ "category": "productivity", "homepage": "https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier" }, + { + "name": "caffeinate", + "description": "Prevents blocking sleep commands by intercepting them and prompting Claude to use background execution instead. Keeps your session responsive during long-running operations.", + "author": { + "name": "Anthropic", + "email": "support@anthropic.com" + }, + "source": "./plugins/caffeinate", + "category": "productivity", + "homepage": "https://github.com/anthropics/claude-plugins-official/tree/main/plugins/caffeinate" + }, { "name": "explanatory-output-style", "description": "Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)", diff --git a/plugins/caffeinate/.claude-plugin/plugin.json b/plugins/caffeinate/.claude-plugin/plugin.json new file mode 100644 index 0000000..aaf7e7c --- /dev/null +++ b/plugins/caffeinate/.claude-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "caffeinate", + "version": "0.1.0", + "description": "Blocks sleep commands and reminds Claude to use background tasks instead", + "author": { + "name": "Anthropic", + "email": "support@anthropic.com" + }, + "keywords": ["productivity", "hooks", "bash", "background-tasks"] +} diff --git a/plugins/caffeinate/README.md b/plugins/caffeinate/README.md new file mode 100644 index 0000000..cd68f8b --- /dev/null +++ b/plugins/caffeinate/README.md @@ -0,0 +1,58 @@ +# Caffeinate + +A Claude Code plugin that blocks `sleep` commands and reminds Claude to use background tasks instead. + +## Purpose + +When Claude uses `sleep` commands in Bash, it blocks the session unnecessarily. This plugin intercepts these commands and suggests using proper async patterns like: + +- `run_in_background: true` parameter for long-running commands +- Polling for conditions instead of sleeping +- Proper async/background task patterns + +## Installation + +```bash +# From the plugin directory +claude --plugin-dir /path/to/caffeinate +``` + +Or copy to your project's `.claude-plugin/` directory. + +## What Gets Blocked + +| Command | Blocked? | Reason | +|---------|----------|--------| +| `sleep 5` | Yes | Direct sleep command | +| `sleep $TIMEOUT` | Yes | Sleep with variable | +| `echo "test" && sleep 5` | Yes | Sleep after separator, outside quotes | +| `cmd; sleep 10` | Yes | Sleep after semicolon | +| `echo "sleep 8 hours"` | No | Sleep is inside quotes (not a command) | +| `echo "foo && sleep 5"` | No | Entire sleep pattern is in a string | + +## How It Works + +The plugin uses a `PreToolUse` hook on the `Bash` tool to: + +1. Check if commands start with `sleep` +2. Detect `sleep` after command separators (`&&`, `||`, `;`, `|`) +3. Use quote-counting to avoid false positives when `sleep` appears inside strings + +## Alternatives to Sleep + +Instead of: +```bash +sleep 5 && check_status +``` + +Use background execution: +```bash +# Run in background with run_in_background: true +long_running_command +``` + +Or poll for conditions: +```bash +# Poll for a file to exist +while [ ! -f /tmp/ready ]; do :; done +``` diff --git a/plugins/caffeinate/hooks/hooks.json b/plugins/caffeinate/hooks/hooks.json new file mode 100644 index 0000000..e441827 --- /dev/null +++ b/plugins/caffeinate/hooks/hooks.json @@ -0,0 +1,17 @@ +{ + "description": "Blocks sleep commands and reminds Claude to use background tasks", + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/check-sleep.sh", + "timeout": 5 + } + ] + } + ] + } +} diff --git a/plugins/caffeinate/hooks/scripts/check-sleep.sh b/plugins/caffeinate/hooks/scripts/check-sleep.sh new file mode 100755 index 0000000..18113be --- /dev/null +++ b/plugins/caffeinate/hooks/scripts/check-sleep.sh @@ -0,0 +1,61 @@ +#!/bin/bash +# Caffeinate hook: Blocks sleep commands and suggests background tasks +set -euo pipefail + +input=$(cat) +command=$(echo "$input" | jq -r '.tool_input.command // empty') + +if [[ -z "$command" ]]; then + exit 0 +fi + +# Allow sleep if run_in_background is true - that's the whole point! +run_in_bg=$(echo "$input" | jq -r '.tool_input.run_in_background // false') +if [[ "$run_in_bg" == "true" ]]; then + exit 0 +fi + +block_message='ACTION REQUIRED: Your sleep command was blocked. You MUST now call Bash again with the SAME command but add the parameter run_in_background: true. Do this immediately in your next tool call. Do not explain or apologize - just retry with run_in_background: true.' + +output_block() { + # Output JSON to stdout for blocking decision + # Output message to stderr to feed back to Claude + cat << EOF +{ + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": "$block_message" + } +} +EOF + exit 0 +} + +# Remove all quoted strings to avoid false positives +# Replace single and double quoted strings with placeholder +cmd_no_quotes=$(echo "$command" | sed -E "s/\"[^\"]*\"//g; s/'[^']*'//g") + +# Check for sleep command patterns in the de-quoted command +# Pattern 1: Command starts with sleep +if [[ "$cmd_no_quotes" =~ (^|[[:space:]])sleep[[:space:]]+[0-9] ]]; then + output_block +fi + +# Pattern 2: sleep after any common separator (&&, ||, ;, |, do, then) +if [[ "$cmd_no_quotes" =~ (\&\&|;\||[[:space:]]do[[:space:]]|[[:space:]]then[[:space:]])[[:space:]]*sleep[[:space:]] ]]; then + output_block +fi + +# Pattern 3: Simple contains check - if "sleep " followed by number appears anywhere +if [[ "$cmd_no_quotes" =~ sleep[[:space:]]+[0-9] ]]; then + output_block +fi + +# Pattern 4: sleep with variable like $TIMEOUT or ${DELAY} +if [[ "$cmd_no_quotes" =~ sleep[[:space:]]+\$ ]]; then + output_block +fi + +# No sleep command detected - allow +exit 0