awake-agent

A CLI tool that keeps your Linux computer awake while locking the screen for a duration you choose — or only while coding agents are actively working. Useful for running long coding agents or background tasks without letting others see or use your machine.

How it works

• Locks the screen using existing Linux tools (loginctl lock-session, xdg-screensaver lock, or desktop D-Bus lock APIs — first one that works is used).
• Prevents sleep/suspend by spawning a detached systemd-inhibit --what=idle:sleep process in the background.
• Two modes:
  • Timer mode — keeps the system awake for a fixed duration, then releases. The computer is not forced to sleep; it just returns to its default behavior.
  • Agent-watch mode — keeps the system awake only while coding agents are actively working. When agents are running commands, editing files, or using CPU, the inhibitor is held. When they go idle (or exit), the inhibitor is released.
• Agent detection scans running processes (ps) for known coding-agent binaries, then assesses real activity:
  • Child processes (running commands)
  • Process state (R/D = busy, S = sleeping)
  • CPU usage sampled over a window
  • Recent file modifications in the agent's working directory

State is tracked in ~/.config/awake-agent/state.json.

Requirements

• Linux (tested with systemd)
• Node.js >= 18
• systemd-inhibit (part of systemd) for sleep inhibition
• A session locker: loginctl (systemd/logind) or xdg-screensaver

Install

npm install -g awake-agent-cli

Usage

# Lock screen and keep the system awake for 2 hours
awake-agent start 2h

# 30 minutes
awake-agent start 30m

# Combined durations
awake-agent start 1h30m

# Without locking the screen
awake-agent start 45m --no-lock

# Default duration is 1 hour
awake-agent start

# Keep awake ONLY while coding agents are running, and lock the screen
awake-agent watch

# Report which coding agents are currently running
awake-agent agents

# Check the active session
awake-agent status

# Stop early (releases the inhibitor immediately)
awake-agent stop

Commands

| Command | Description | | --- | --- | | start [duration] | Start a background timer session and lock the screen | | watch | Keep awake only while coding agents work, and lock the screen | | agents | Report which coding agents are running and whether they are active | | stop | Stop the active session and release the inhibitor | | status | Show whether a session is active and remaining time |

Options

| Option | Applies to | Description | | --- | --- | --- | | -d, --duration <duration> | start | Duration if not passed as the positional argument | | --no-lock | start, watch | Do not lock the screen |

Detected coding agents

The agents command and watch mode detect these known agents by process name:

• Claude Code, OpenAI Codex, OpenCode, Aider, Gemini CLI, Cursor, Goose, Copilot CLI, Qwen Code, Amp, Cline

Activity detection

An agent is considered active if any of these are observed:

• It has running child processes (a command is executing)
• It or its children are in a busy process state (R/D)
• It uses ≥ 2% CPU during a 2-second sampling window
• Files in its working directory were modified in the last 30 seconds

awake-agent agents reports each detected agent with an active/idle status and the evidence. In watch mode the sleep inhibitor is held only while at least one agent is active.

Duration formats

• Plain number: 30 (treated as minutes)
• Units: s (seconds), m (minutes), h (hours), d (days)
• Combined: 1h30m, 2d 4h

Examples: 30s, 15m, 2h, 1h30m, 1d

Behavior details

• Only one session can run at a time. Starting a new one while one is active prints a message; use stop first.
• The session runs entirely in the background — you can close your terminal after start or watch.
• When a timer expires, the tool stops keeping the computer awake; it does not force sleep.
• In agent-watch mode, the system is kept awake only while at least one coding agent is active; when all are idle or gone, the inhibitor is released.
• If no locker is available, start/watch prints a warning but still keeps the system awake.

License

MIT