cpu-wait

cpu-wait

A CLI tool that waits for CPU load to drop below a threshold before executing commands. Perfect for running resource-intensive tasks only when your system has available capacity.

Installation

Using npx (no installation required)

npx cpu-wait <command>

Global installation

npm install -g cpu-wait

Local installation

npm install cpu-wait

Usage

Basic usage

Wait for CPU usage to drop below 80% for 60 seconds, then run a command:

npx cpu-wait -- npm run build

Custom threshold

Wait for CPU usage below 50%:

npx cpu-wait --threshold 50 -- make all

Custom duration

Wait for CPU to be low for 30 seconds:

npx cpu-wait --duration 30 -- ./heavy-process.sh

Verbose mode

See detailed progress:

npx cpu-wait --verbose -- python train_model.py

Quiet mode

Suppress all output except errors:

npx cpu-wait --quiet -- rsync -av source/ dest/

Options

• -t, --threshold <percent> - CPU usage threshold percentage (default: 80)
• -d, --duration <seconds> - Duration CPU must stay below threshold (default: 60)
• -i, --interval <seconds> - Check interval in seconds (default: 5)
• -v, --verbose - Show detailed progress messages
• -q, --quiet - Suppress all output except errors
• -h, --help - Display help
• -V, --version - Display version

Examples

Build project when CPU is available

npx cpu-wait -- npm run build

Run backup when system is idle

npx cpu-wait --threshold 30 --duration 120 -- ./backup.sh

Process video files when CPU is low

npx cpu-wait --threshold 50 -- ffmpeg -i input.mp4 -c:v libx264 output.mp4

Chain multiple commands

npx cpu-wait -- bash -c "npm test && npm run build && npm run deploy"

Use in npm scripts

Add to your package.json:

{
  "scripts": {
    "build:when-idle": "npx cpu-wait -- npm run build",
    "test:when-idle": "npx cpu-wait --threshold 70 -- npm test"
  }
}

How it works

• The tool monitors CPU usage at regular intervals (default: every 5 seconds)
• When CPU usage drops below the threshold (default: 80%), it starts a timer
• If CPU stays below the threshold for the specified duration (default: 60 seconds), the command executes
• If CPU exceeds the threshold during the wait period, the timer resets
• The command runs with the same environment variables and working directory

Programmatic Usage (TypeScript/JavaScript)

You can also use cpu-wait as a library in your Node.js applications:

Installation

npm install cpu-wait

Basic Usage

import { waitCpu } from 'cpu-wait';

// Wait with default settings (80% threshold, 60s duration)
await waitCpu();
console.log('CPU is now available!');

// Custom options
await waitCpu({
  threshold: 50,    // Wait for CPU < 50%
  duration: 30,     // For 30 seconds
  interval: 2,      // Check every 2 seconds
  onProgress: (msg) => console.log(msg)  // Progress callback
});

Advanced Example

import { waitCpu, WaitCpuOptions } from 'cpu-wait';

async function runHeavyTask() {
  const options: WaitCpuOptions = {
    threshold: 70,
    duration: 45,
    interval: 3,
    onProgress: (message) => {
      console.log(`[CPU Monitor] ${message}`);
    }
  };

  try {
    console.log('Waiting for optimal CPU conditions...');
    await waitCpu(options);

    // Your heavy computation here
    console.log('Starting heavy computation...');
    await heavyComputation();

  } catch (error) {
    console.error('Failed to wait for CPU:', error);
  }
}

TypeScript Types

interface WaitCpuOptions {
  threshold?: number;    // CPU threshold percentage (0-100)
  duration?: number;     // Duration in seconds
  interval?: number;     // Check interval in seconds
  onProgress?: (message: string) => void;  // Progress callback
}

Use Cases

• CI/CD pipelines: Run builds when agents have capacity
• Batch processing: Process data when servers are idle
• Development: Run heavy tasks without interrupting other work
• Server maintenance: Schedule intensive operations during low-usage periods
• Resource management: Prevent system overload by queuing tasks
• Node.js applications: Integrate CPU monitoring into your applications

Requirements

• Node.js >= 14.0.0
• Works on Linux, macOS, and Windows

License

MIT

Author

snomiao

Contributing

Issues and pull requests are welcome at GitHub