caffeinate for Linux

Prevent your Linux system from sleeping — just like macOS

A lightweight, battery-aware, Linux-only reimplementation of macOS’s caffeinate command. Prevents idle sleep, display sleep, or full system sleep — safely and efficiently.

Perfect for:

• Long downloads/uploads
• Remote sessions
• Presentations or demos
• Unattended builds or backups

⚡ No disk sleep support (-m) — intentionally excluded for simplicity and portability.

---

✨ Features

• ✅ Prevent idle sleep (-i) — safe on battery
• ✅ Prevent full sleep (-s) — only on AC power
• ✅ Wake display & simulate user activity (-u)
• ✅ Prevent display sleep (-d) — supports GNOME, KDE, XFCE, LXQt, MATE, Cinnamon, COSMIC
• ✅ Run with command, PID, or timeout
• ✅ Verbose mode (-v) for transparency
• ✅ Auto-cleanup on exit, timeout, or crash
• ✅ Cross-platform compatibility — works across Ubuntu, Debian, Arch, RedHat, and derivatives
• ✅ Enhanced AC detection — supports multiple AC adapter names (AC, ADP, etc.)
• ✅ Zero dependencies beyond systemd & Bash

---

📦 Installation

One-liner (recommended)

curl -fsSL https://raw.githubusercontent.com/ArpitSuthar/caffeinate-linux/main/caffeinate \
  | sudo install -m 755 /dev/stdin /usr/local/bin/caffeinate

Manual install

# Download script
wget https://raw.githubusercontent.com/ArpitSuthar/caffeinate-linux/main/caffeinate
chmod +x caffeinate

# Install
sudo install -m 755 caffeinate /usr/local/bin/

# (Optional) Install man page
sudo install -Dm644 caffeinate.1 /usr/local/share/man/man1/caffeinate.1
sudo mandb  # refresh man database

🛠️ Make

Install (default: /usr/local)

make
sudo make install

Install to custom prefix (e.g., for testing)

make PREFIX=/tmp/test
make install DESTDIR=/tmp/staging

Uninstall

sudo make uninstall

Validate before commit

make validate

✅ Works on Ubuntu, Fedora, Debian, Arch, and any systemd-based desktop Linux.

---

🚀 Usage

# Keep system awake until you press Ctrl+C
caffeinate

# Keep awake for 1 hour
caffeinate -t 3600

# Simulate user activity (wake screen, reset idle timer)
caffeinate -u -t 600

# Run a command with idle sleep prevented
caffeinate -i ./long_task.sh

# Wait until a background process (PID 1234) exits
caffeinate -i -w 1234

# Verbose mode (see what's happening)
caffeinate -v -d -t 120

💡 Note: -t is ignored when used with a command or -w.

---

🔋 Battery Safety

• Full sleep prevention (-s) is automatically disabled on battery.
• Only low-impact idle prevention (-i) is allowed when unplugged.
• AC detection uses upower or /sys/class/power_supply.

---

⚙️ Requirements

• systemd (for systemd-inhibit)
• bash 4+
• D-Bus session (for display control in GNOME/KDE/XFCE/LXQt/MATE/Cinnamon/COSMIC)
• Optional: upower (improves AC detection)
• Optional: gdbus, qdbus, xset (enhanced desktop environment support)

Works over SSH — skips display actions when no GUI is detected. Supports multiple AC adapter names (AC, ADP, etc.) for broader hardware compatibility.

---

📚 Man Page

After installing the man page:

man caffeinate

---

🧪 Testing

A comprehensive test suite is included to verify all functionality:

# Run all tests
bash test_caffeinate_fixed.sh

# Expected: 29/30 tests passing (1 skipped due to race conditions)

Test Coverage

• ✅ All individual flags and combinations
• ✅ Command execution and PID waiting
• ✅ Error handling and edge cases
• ✅ Cross-platform compatibility
• ✅ Resource cleanup and signal handling

CI/CD Integration

# GitHub Actions example
- name: Run tests
  run: bash test_caffeinate_fixed.sh

See TESTING.md for complete testing documentation.

---

📄 License

MIT License — free to use, modify, and distribute.

---

🙌 Inspired By

• macOS caffeinate
• Windows PowerToys Awake

---

🤖 AI-Assisted Development

This tool was designed and implemented with the assistance of a large language model (LLM). The core logic, script, man page, and build automation were co-developed through iterative collaboration with an AI agent to ensure correctness, efficiency, and adherence to macOS caffeinate semantics — while respecting Linux power management standards.