· 5 min read
Wait for idle. Then execute.
You're working on something important. In the background, a build kicks off. CPU spikes to 100%. Your editor freezes. Your patience runs out.
There's a better way.
Heavy tasks compete with your active work:
Running them immediately means:
A CLI tool that waits for CPU to drop below a threshold before executing:
npx cpu-wait -- npm run build
The build starts only when your system is idle.
┌─────────────────────────────────────────────────────────┐
│ CPU Usage Over Time │
│ │
│ 100% ─ ▓▓▓▓▓▓▓▓ │
│ 80% ─ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ─ ─ ─ threshold ─ ─ ─ ─ ─ │
│ 60% ─ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │
│ 40% ─ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ │
│ 20% ─ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░ │
│ 0% ─────────────────────────────────────▶ │
│ ↑ │
│ Command executes │
└─────────────────────────────────────────────────────────┘
npx cpu-wait -- npm run build
Default: Wait for CPU < 80% for 60 seconds.
# Wait for CPU below 50%
npx cpu-wait --threshold 50 -- npm run build
# Wait for CPU to be low for 30 seconds
npx cpu-wait --duration 30 -- ./heavy-script.sh
npx cpu-wait \
--threshold 40 \
--duration 120 \
--interval 2 \
--verbose \
-- npm run test
| Flag | Default | Description |
|---|---|---|
-t, --threshold |
80 | CPU usage threshold (%) |
-d, --duration |
60 | How long CPU must stay below threshold (s) |
-i, --interval |
5 | Check interval (s) |
-v, --verbose |
off | Show detailed progress |
-q, --quiet |
off | Suppress all output |
# Development: build without interrupting coding
npx cpu-wait -- npm run build
# Run backup only when system is truly idle
npx cpu-wait --threshold 30 --duration 120 -- ./backup.sh
# Don't compete with other work
npx cpu-wait --threshold 50 -- ffmpeg -i input.mp4 -c:v libx264 output.mp4
# Run entire pipeline when resources are free
npx cpu-wait -- bash -c "npm test && npm run build && npm run deploy"
{
"scripts": {
"build:when-idle": "npx cpu-wait -- npm run build",
"test:when-idle": "npx cpu-wait --threshold 70 -- npm test"
}
}
Use as a library in Node.js applications:
import { waitCpu } from 'cpu-wait';
// Wait with defaults
await waitCpu();
console.log('CPU is available!');
// Run your heavy code
await processData();
await waitCpu({
threshold: 50,
duration: 30,
interval: 2,
onProgress: (msg) => console.log(msg)
});
import { waitCpu } from 'cpu-wait';
async function scheduleHeavyWork() {
console.log('Waiting for optimal conditions...');
await waitCpu({
threshold: 60,
duration: 45,
onProgress: (message) => {
updateStatusBar(`[CPU] ${message}`);
}
});
console.log('Starting heavy work...');
await runExpensiveOperation();
}
# GitHub Actions: Wait for agent capacity
steps:
- run: npx cpu-wait -- npm run build
name: Build when agent is ready
# In terminal 1: Active development
vim src/app.ts
# In terminal 2: Tests wait for you to stop typing
npx cpu-wait --threshold 60 -- npm test
// Process files without overwhelming the system
for (const file of files) {
await waitCpu({ threshold: 70, duration: 10 });
await processFile(file);
}
# Run maintenance only during low traffic
npx cpu-wait --threshold 20 --duration 300 -- ./maintenance.sh
// Custom job queue with CPU awareness
const queue = new JobQueue();
queue.process(async (job) => {
await waitCpu({ threshold: 60 });
return await executeJob(job);
});
nice lowers process priority but doesn't prevent concurrent execution. Your heavy task still runs immediately, just slower. cpu-wait defers execution entirely until resources are free.
Job queues (Bull, Agenda) add infrastructure. Redis or MongoDB dependencies. Configuration overhead. cpu-wait is a single command with zero setup.
Scheduling at off-hours works for predictable loads but:
cpu-wait responds to actual system state, not time.
The tool samples CPU usage across all cores:
Total Usage = (user + system + nice) / (user + system + nice + idle) × 100
Sampling happens at the configured interval (default: 5 seconds). The average is compared against your threshold.
Works on:
Same API, same behavior across platforms.
The monitoring itself is lightweight:
# Global
npm install -g cpu-wait
# Or use directly
npx cpu-wait -- your-command
Computers should wait for humans, not the other way around.
Heavy tasks are important, but they're rarely urgent. Let them wait for the right moment. Your active work always gets priority.
Install: npm install -g cpu-wait
GitHub: github.com/snomiao/cpu-wait
Snowstar Miao builds tools that respect developer workflow.