KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #dsh-plugin #ai-agent #mcp #deepseek-harness #windows #open-source

narcolepsyd

★ 13 Open GitHub ↗

Idle power optimizer for Linux laptops with Intel hybrid CPUs

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# narcolepsyd

An idle power optimizer for Linux laptops with Intel hybrid CPUs.

narcolepsyd monitors keyboard and touchpad input. When you stop interacting with your laptop, it aggressively parks CPU cores and reduces power consumption. When you touch any input device, everything is restored instantly.

Your display stays on. Your network stays connected. There's no visible flicker or delay.

## Why

Modern Intel hybrid CPUs (Alder Lake and newer) have three tiers of CPU cores: Performance (P-cores), Efficiency (E-cores), and Low-Power Efficiency (LP E-cores). Linux keeps all of them powered and ready even when you're staring at a static screen.

Windows has Intel DPTF/DTT, a proprietary framework that coordinates power management across CPU, GPU, and display. Linux doesn't have an equivalent. narcolepsyd bridges part of that gap.

On a Fujitsu LIFEBOOK UH with a 31 Wh battery, narcolepsyd reduced idle system power by measurably extending battery life during typical use (reading, thinking, waiting for builds).

## What it does

When idle (no keyboard/touchpad input for 3 seconds):

- **Parks P-cores** and most E-cores, keeping only 2 E-cores + LP E-cores online
- **Caps remaining core frequencies** to 800 MHz
- **Sets EPP** (Energy Performance Preference) to maximum power saving on all cores
- **Disables turbo boost**
- **Suspends non-essential USB devices** (webcam, fingerprint reader)

When you press a key or touch the trackpad:

- All cores come back online (typically <50ms)
- Frequencies, EPP, and turbo are restored to their previous values
- USB devices are resumed

## Supported hardware

Any Linux laptop with an Intel hybrid CPU using the `intel_pstate` driver:

- **Alder Lake** (12th Gen) — Core i5/i7/i9-12xxx
- **Raptor Lake** (13th/14th Gen) — Core i5/i7/i9-13xxx/14xxx
- **Meteor Lake** (Core Ultra Series 1) — Core Ultra 5/7/9 1xxU/H
- **Lunar Lake** (Core Ultra Series 2) — Core Ultra 5/7/9 2xxV
- **Arrow Lake** (Core Ultra Series 2) — Core Ultra 5/7/9 2xxH/HX
- **Panther Lake** and newer — should work automatically

narcolepsyd auto-detects your CPU topology. No configuration needed.

## Install

### From .deb (Ubuntu/Debian)

Download the latest `.deb` from [Releases](https://github.com/obra/narcolepsyd/releases):

```bash
sudo dpkg -i narcolepsyd_*.deb
sudo systemctl enable --now narcolepsyd
```

### From source

```bash
cargo build --release
sudo cp target/release/narcolepsyd /usr/local/bin/
sudo cp dist/narcolepsyd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now narcolepsyd
```

## Usage

narcolepsyd runs as a systemd service. It requires root (for CPU hotplug and `/dev/input` access).

```bash
# Check status
systemctl status narcolepsyd

# View logs
journalctl -u narcolepsyd

# Verbose logging (debug transitions)
sudo RUST_LOG=debug narcolepsyd
```

### Signals

- `SIGTERM` / `SIGINT` — graceful shutdown, restores all power settings
- Power state is always restored on exit, even on crash

## Configuration

narcolepsyd currently has no configuration file. It uses sensible defaults:

| Setting | Value |
|---------|-------|
| Idle timeout | 3 seconds |
| E-cores kept online | 2 |
| Low-power frequency cap | 800 MHz |
| Only on battery | Yes |

These will be configurable in a future release.

## How it works

1. Opens `/dev/input/event*` devices and identifies keyboards and pointing devices
2. Uses `poll(2)` to wait for input events with zero CPU overhead while waiting
3. After 3 seconds of silence, writes to sysfs to offline cores, cap frequencies, and set EPP
4. On any input event, immediately restores everything via sysfs
5. Periodically checks AC power state and inhibitor processes (zoom, ffmpeg, etc.)

The daemon itself consumes effectively zero CPU — it spends all its time blocked in `poll(2)`.

## Safety

- **Always restores state on exit** — SIGTERM, SIGINT, and panics all trigger cleanup
- **Won't run on AC power** — only activates on battery
- **Respects inhibitors** — won't park cores while zoom, ffmpeg, vlc, or similar are running
- **CPU 0 is never offlined** — Linux requires at least one CPU online
- **Display is never touched** — no screen blanking, no suspend, no flicker

## License

Apache 2.0. See [LICENSE](LICENSE).

narcolepsyd

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README