Skip to content

CLAUDE.md

Latest commit

 

History

History
111 lines (81 loc) · 3.46 KB

CLAUDE.md

File metadata and controls

111 lines (81 loc) · 3.46 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Codebase Overview

This is a Linux reimplementation of macOS's caffeinate command - a lightweight bash script that prevents system sleep using systemd-inhibit and D-Bus. The project consists of:

  • Main script: caffeinate (Bash script, ~7.4KB)
  • Man page: caffeinate.1 (troff format)
  • Build system: Makefile with install/uninstall targets
  • Documentation: README.md with usage examples

Architecture

Core Components

  1. Argument Parsing (parse_args()): Handles command-line flags (-d, -i, -s, -u, -t, -w, -v)
  2. Power Management:
    • check_ac_power(): Detects AC power using upower or sysfs
    • Battery safety: Automatically disables full sleep prevention (-s) on battery
  3. Display Management:
    • has_gui_session(): Detects GUI environment (X11/Wayland)
    • simulate_user_activity(): Uses gdbus/dbus-send to wake displays
    • inhibit_display_sleep(): Prevents display sleep via D-Bus
  4. System Sleep Prevention: Uses systemd-inhibit with modes: idle, sleep, or both
  5. Execution Modes:
    • Command mode: Runs a command with sleep prevention
    • Wait mode: Waits for a PID to exit (-w)
    • Timeout mode: Runs for specified duration (-t)
    • Interactive mode: Runs until Ctrl+C

Key Features

  • Battery-aware: Full sleep prevention only works on AC power
  • GUI detection: Skips display operations in headless/SSH sessions
  • Auto-cleanup: Uses trap handlers to clean up child processes
  • Verbose logging: Optional debug output via -v flag

Development Commands

Build & Install

# Validate script syntax
make validate

# Install to default location (/usr/local)
make install

# Install to custom prefix
make PREFIX=/custom/path install

# Uninstall
make uninstall

# Show help
make help

Testing

# Run syntax validation
bash -n caffeinate

# Test basic functionality (5 second timeout)
./caffeinate -t 5

# Test with verbose logging
./caffeinate -v -t 5

# Test display wake (if GUI available)
./caffeinate -u -t 5

# Test command execution
./caffeinate -i sleep 3

Manual Testing Scenarios

  1. Battery vs AC behavior: Test -s flag on both power sources
  2. GUI detection: Test display operations in both GUI and SSH sessions
  3. Process cleanup: Verify child processes are terminated on Ctrl+C
  4. Timeout accuracy: Check if -t durations are respected
  5. PID waiting: Test -w with various process lifetimes

Important Implementation Details

  1. systemd-inhibit: Core mechanism for preventing sleep
  2. D-Bus integration: Used for display wake/sleep control (GNOME/KDE)
  3. Power detection: Falls back from upower to sysfs if needed
  4. Process management: Uses trap for cleanup and pkill for child process termination
  5. Error handling: Uses set -euo pipefail for strict bash error handling

File Structure

  • caffeinate: Main bash script (entry point)
  • caffeinate.1: Manual page (troff format)
  • Makefile: Build/install system
  • README.md: User documentation
  • LICENSE: MIT license

Key Functions

  • parse_args(): Command-line argument processing
  • check_ac_power(): AC power detection
  • simulate_user_activity(): Display wake via D-Bus
  • inhibit_display_sleep(): Display sleep prevention
  • wait_for_pid(): Process waiting logic
  • main(): Orchestrates all functionality