cc-caffeine 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,70 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine caffeinate"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine caffeinate"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine caffeinate"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine uncaffeinate"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine uncaffeinate"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx cc-caffeine uncaffeinate"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+    "name": "cc-caffeine",
+    "description": "Prevents your computer from sleeping while Claude Code works hard",
+    "version": "0.2.0",
+    "author": {
+        "name": "Samuel Berthe",
+        "email": "hey@samuel-berthe.fr"
+    },
+    "homepage": "https://github.com/samber/cc-caffeine",
+    "repository": "https://github.com/samber/cc-caffeine",
+    "license": "MIT",
+    "keywords": [
+        "claude-code",
+        "claude-code-plugin",
+        "plugin",
+        "nap",
+        "sleep",
+        "sleep-prevention",
+        "caffeine",
+        "caffeinate",
+        "system-tray"
+    ]
+}

package/.eslintrc.json

@@ -0,0 +1,36 @@
+{
+  "env": {
+    "browser": true,
+    "es2021": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "rules": {
+    "indent": ["error", 2],
+    "linebreak-style": ["error", "unix"],
+    "quotes": ["error", "single"],
+    "semi": ["error", "always"],
+    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "no-console": "off",
+    "prefer-const": "error",
+    "no-var": "error",
+    "object-shorthand": "error",
+    "prefer-arrow-callback": "error",
+    "arrow-spacing": "error",
+    "comma-dangle": ["error", "never"],
+    "eol-last": "error",
+    "no-trailing-spaces": "error",
+    "space-before-blocks": "error",
+    "keyword-spacing": "error",
+    "space-infix-ops": "error",
+    "no-multiple-empty-lines": ["error", { "max": 2 }],
+    "brace-style": ["error", "1tbs"],
+    "curly": "error"
+  }
+}

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [samber]

package/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: monthly

package/.github/workflows/build.yml

@@ -0,0 +1,79 @@
+name: CI Checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 14.x
+          - 16.x
+          - 18.x
+          - 20.x
+          - 22.x
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      
+    - name: Setup Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+        
+    - name: Install dependencies
+      run: npm install
+
+    - name: Check version numbers match
+      run: |
+        # Extract version from package.json
+        PACKAGE_VERSION=$(node -p "require('./package.json').version")
+        echo "Package version: $PACKAGE_VERSION"
+        
+        # Extract version from plugin.json
+        if [ -f ".claude-plugin/plugin.json" ]; then
+          PLUGIN_VERSION=$(node -p "require('./.claude-plugin/plugin.json').version")
+          echo "Plugin version: $PLUGIN_VERSION"
+          
+          # Check if versions match
+          if [ "$PACKAGE_VERSION" != "$PLUGIN_VERSION" ]; then
+            echo "❌ Version mismatch detected!"
+            echo "Package version: $PACKAGE_VERSION"
+            echo "Plugin version: $PLUGIN_VERSION"
+            exit 1
+          else
+            echo "✅ Versions match: $PACKAGE_VERSION"
+          fi
+        else
+          echo "⚠️ Warning: .claude-plugin/plugin.json not found"
+          exit 1
+        fi
+        
+    - name: Test version command
+      run: |
+        # Test that our version command works correctly
+        node caffeine.js version
+        
+    - name: Test other commands (syntax check)
+      run: |
+        # Test that other commands don't have syntax errors
+        node caffeine.js --help || true
+        
+    - name: Run linting (if available)
+      run: npm run lint || echo "⚠️ Linting skipped (not configured)"
+
+    - name: Run formatting check (if available)
+      run: |
+        if command -v prettier &> /dev/null; then
+          npm run format
+          git diff --exit-code || echo "⚠️ Code formatting changes detected"
+        else
+          echo "⚠️ Formatting check skipped (prettier not available)"
+        fi

package/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "semi": true,
+  "trailingComma": "none",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}

package/CLAUDE.md

@@ -0,0 +1,307 @@
+# CC-Caffeine: Claude Code Sleep Prevention System
+
+A Node.js/Electron script that prevents your computer from going to sleep while using Claude Code through system tray integration and session management.
+
+## Architecture
+
+The system consists of a modular architecture with the following components:
+
+### Core Modules
+
+1. **caffeine.js** - Main entry point that orchestrates all modules and handles command routing
+2. **src/commands.js** - Handles command-line interface functionality and process management
+3. **src/session.js** - Manages session persistence with file locking and timeout handling
+4. **src/server.js** - Handles server process management and Electron integration
+5. **src/system-tray.js** - Manages system tray functionality and sleep prevention
+6. **src/electron.js** - Wraps Electron-specific functionality and provides cross-platform support
+
+### User Commands
+
+1. **caffeinate command** - Adds session to JSON file and ensures server is running
+2. **uncaffeinate command** - Removes session from JSON file
+3. **server command** - Starts Electron system tray application that polls JSON file for active sessions
+4. **version command** - Shows version information from package.json and plugin.json
+
+## Features
+
+- Cross-platform support (Linux, macOS, Windows)
+- Headless Electron system tray (no windows, only system tray)
+- JSON file for session persistence with proper-lockfile for concurrency
+- Automatic session timeout (15 minutes of inactivity)
+- Auto-server startup when not running
+- Multiple concurrent session support
+- Real-time status monitoring
+- Lightweight client commands (no Electron dependency for caffeinate/uncaffeinate)
+- Native sleep prevention using Electron's powerSaveBlocker API
+- Hidden from macOS dock using app.dock.hide()
+
+## Technical Stack
+
+- **Node.js 14+** - Runtime environment with modern JavaScript features
+- **Electron 28+** - Cross-platform desktop application framework
+- **proper-lockfile** - File locking for all concurrent access with retry logic
+- **Electron powerSaveBlocker** - Native cross-platform sleep prevention
+- **Electron Tray/Menu** - System tray functionality
+- **JSON file** - Session storage and communication
+- **setInterval** - Background polling for session changes
+
+## Commands Usage
+
+### caffeinate
+Enables sleep prevention for the current session (lightweight, no system tray).
+```bash
+node caffeine.js caffeinate
+# or
+npm run caffeinate
+```
+Accepts JSON via stdin with session_id:
+```json
+{"session_id": "abc123"}
+```
+
+### uncaffeinate
+Disables sleep prevention for the current session (lightweight, no system tray).
+```bash
+node caffeine.js uncaffeinate
+# or
+npm run uncaffeinate
+```
+Accepts JSON via stdin with session_id:
+```json
+{"session_id": "abc123"}
+```
+
+### server
+Starts the headless Electron caffeine server with system tray only.
+```bash
+node caffeine.js server
+# or
+npm run server
+# or
+npm start
+```
+
+**Cross-platform background operation:**
+```bash
+npm run server  # Completely headless - no windows, only system tray
+```
+
+### version
+Shows version information from both package.json and .claude-plugin/plugin.json.
+```bash
+node caffeine.js version
+# or
+npm run version
+```
+
+Output example:
+```
+=== CC-Caffeine Version ===
+Package version: 0.1.1
+Plugin version:  0.1.1
+```
+
+## Installation & Setup
+
+1. Install Node.js dependencies:
+```bash
+npm install
+```
+
+2. Create config directory:
+```bash
+mkdir -p ~/.claude/plugins/cc-caffeine
+```
+
+3. Make the script executable (optional):
+```bash
+chmod +x caffeine.js
+```
+
+4. Configure Claude Code hooks (example):
+```json
+{
+  "hooks": {
+     "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/caffeine.js caffeinate"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /path/to/caffeine.js uncaffeinate"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note: The server will be auto-started by the caffeinate command when needed.
+
+## JSON File Structure
+
+JSON file located at: `~/.claude/plugins/cc-caffeine/sessions.json`
+
+```json
+{
+  "sessions": {
+    "session_id_abc123": {
+      "created_at": "2025-01-08T10:30:00.000Z",
+      "last_activity": "2025-01-08T10:45:00.000Z"
+    }
+  },
+  "last_updated": "2025-01-08T10:45:00.000Z"
+}
+```
+
+Sessions are removed automatically after 15 minutes of inactivity.
+
+## File Concurrency
+
+- **proper-lockfile** ensures atomic read/write operations
+- File locking prevents corruption when multiple processes access simultaneously
+- Short lock duration - Lock only held during actual read/write operations
+- Built-in retry mechanism with configurable timeout
+- Cross-platform file locking using OS primitives
+- Atomic session operations (add/remove) within single lock to prevent race conditions
+
+## Session Management
+
+- Sessions auto-expire after 15 minutes of inactivity
+- Automatic cleanup of expired sessions during every add/remove operation
+- Server polls JSON file every 10 seconds for active sessions (with file locking)
+- Multiple sessions can be active simultaneously
+- Sleep prevention is active when at least one session is active
+- Commands auto-start server if not running
+- Only server command loads Electron system tray (lightweight client commands)
+- All session operations are atomic within file locks to prevent corruption
+- Session timestamps: `created_at` preserved, `last_activity` updated on subsequent calls
+- All JSON file operations (read/write) are protected with proper-lockfile
+- Client commands (caffeinate/uncaffeinate) work without Electron dependency
+
+## System Tray
+
+- Headless Electron application - no windows ever created
+- Shows custom icon when caffeinated/inactive
+- Context menu with Exit button
+- Hidden from macOS dock using `app.dock.hide()`
+- Cross-platform system tray support
+
+## Running Without Console Window
+
+The Electron server is completely headless:
+
+```bash
+# Start headless server (no windows, only system tray)
+npm run server
+# or
+npm start
+```
+
+### Platform-Specific Background Operation:
+
+**macOS:**
+- Hidden from dock using `app.dock.hide()`
+- System tray only operation
+- Native sleep prevention
+
+**Windows/Linux:**
+- Background process with system tray
+- No console windows created
+- Native sleep prevention
+
+## Development Scripts
+
+Additional npm scripts for development:
+
+```bash
+npm run version   # Show version information from package.json and plugin.json
+npm run lint      # Run ESLint (if installed)
+npm run format    # Format code with Prettier (if installed)
+```
+
+## Module Import Structure
+
+The application uses CommonJS modules with clear dependency hierarchy:
+
+- `caffeine.js` imports from `src/commands.js` and `src/server.js`
+- `src/commands.js` imports from `src/session.js`
+- `src/server.js` imports from `src/session.js`, `src/system-tray.js`, and `src/electron.js`
+- `src/system-tray.js` imports from `src/session.js` and `src/electron.js`
+- `src/electron.js` provides Electron functionality on-demand
+
+## Sleep Prevention
+
+- Uses **Electron's powerSaveBlocker** for cross-platform sleep prevention
+- `powerSaveBlocker.start('prevent-app-suspension')` blocks system sleep and app suspension
+- Automatically activates when sessions are active
+- Gracefully releases sleep prevention on shutdown
+- Works on Windows, macOS, and Linux
+
+## File Structure
+
+```
+caffeine.js          - Main entry point and command routing
+src/
+└── commands.js          - Command-line interface and process management
+└── session.js           - Session persistence and file locking
+└── server.js            - Server process management and Electron integration
+└── system-tray.js       - System tray functionality and sleep prevention
+└── electron.js          - Electron-specific functionality wrapper
+package.json         - Node.js dependencies and scripts
+icon-coffee-full.png - Active caffeine icon (PNG)
+icon-coffee-empty.png- Inactive caffeine icon (PNG)
+icon-coffee-full.svg - Active caffeine icon (SVG)
+icon-coffee-empty.svg- Inactive caffeine icon (SVG)
+~/.claude/plugins/cc-caffeine/
+└── sessions.json    - JSON file with session data
+```
+
+**Modular architecture benefits:**
+- Separation of concerns for better maintainability
+- Individual modules can be tested independently
+- Clear separation between Electron-dependent and lightweight client code
+- Easier to extend and modify specific functionality
+- Better code organization and readability
+
+## Error Handling
+
+- Graceful server startup fallback if Electron unavailable
+- JSON file read/write error recovery with proper-lockfile
+- All operations protected by file locks to prevent race conditions
+- Atomic session operations prevent data corruption during concurrent access
+- Session cleanup on process termination
+- Cross-platform path handling using Node.js path module
+- Lock timeout handling with proper error messages
+- Automatic expired session cleanup during every operation
+- Proper powerSaveBlocker cleanup on server shutdown
+- Graceful error handling for missing Electron APIs
+
+## Cross-platform
+
+- Native MacOS/Windows/Linxe sleep prevention via Electron
+- Compatible with OS security permissions and system tray
+- Background process
+
+## Security Considerations
+
+- Session validation and timeout protection
+- No external network connections required
+- File access restricted to user's home directory
+- Process isolation between client commands and Electron server
+
+## Performance Considerations
+
+- Minimal memory footprint
+- Efficient polling with 5-second intervals
+- Fast startup time (< 1 seconds for Electron)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Samuel Berthe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.