Skip to content
8ffPublic

About

Battery charge thresholds, sensors, keep-awake and screens-off for Linux laptops, in one self-updating binary.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

laptopctl

One small binary that makes a Linux laptop behave.
Cap the battery charge, read every sensor, keep the machine awake, switch the screens off.

Latest release CI License: AGPL-3.0-or-later

$ laptopctl
Battery: BAT0
Power: plugged in
Status: Not charging
Charge: 96%
Start threshold: 75%
End threshold: 80%
Health: 90.9% (80 cycles)
Sensors: 47.8°C max, fans 2970 RPM

awake: on (pid 492677, 11h24m left)
display: stays on

That is a laptop on its charger that is not charging: the battery is above its 80% stop threshold, so the machine runs from the wall and leaves the cells alone. It is also being held awake for another eleven hours, and it will let go on its own.

What it does

  • Battery care. Set the charge thresholds that keep a docked battery away from 100%, with presets for daily use and for a full charge before a trip. See capacity, health and cycle count.
  • Keep awake. Like Amphetamine or caffeinate on macOS: stay awake for a duration, until a time of day, or for the working day, then go back to normal by itself.
  • Screens off. Turn every display off right now while the laptop keeps working. The next key press or mouse movement brings them back.
  • Sensors. Every temperature and fan the kernel knows about, without installing lm-sensors.
  • Self-updating. laptopctl update installs the latest release, verified against its checksum.

It is a single static binary with no configuration file and no runtime dependencies. Nothing runs in the background unless you ask for it.

Install

curl -fsSL https://raw.githubusercontent.com/8ff/laptopctl/main/install.sh | sh

That downloads the latest release for your machine (x86-64 or arm64), checks it against the release's SHA256SUMS and installs it to ~/.local/bin/laptopctl. It doesn't use sudo. From then on, laptopctl update keeps it current.

Set LAPTOPCTL_INSTALL_DIR to install somewhere else. install.sh is short if you would like to read it first.

Other ways to install

By hand, the same steps the script runs:

arch=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
cd "$(mktemp -d)"
curl -fsSLO "https://github.com/8ff/laptopctl/releases/latest/download/laptopctl-linux-$arch"
curl -fsSLO "https://github.com/8ff/laptopctl/releases/latest/download/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS
install -Dm755 "laptopctl-linux-$arch" ~/.local/bin/laptopctl

With Go:

go install github.com/8ff/laptopctl@latest

From source:

git clone https://github.com/8ff/laptopctl
cd laptopctl
go build -o ~/.local/bin/laptopctl .

Usage

Run laptopctl on its own for the overview above, or laptopctl help for every command.

Battery

laptopctl battery                  # charge, thresholds, health
laptopctl battery health           # design and full capacity, health, cycles
laptopctl battery daily            # stop charging at 80%, resume below 75%
laptopctl battery full             # allow a full charge (0/100), for travel days
laptopctl battery set 60 70        # any start and stop thresholds you like
laptopctl battery persist          # reapply the current thresholds at every boot
$ laptopctl battery health
Battery: BAT0
Design capacity: 50.5 Wh
Full capacity: 45.9 Wh
Health: 90.9%
Cycles: 80

Writing thresholds needs root, so set, daily, full and persist ask for sudo themselves. Everything else runs as you.

persist installs a small systemd unit, laptopctl-battery.service, for hardware that forgets its thresholds when powered off. laptopctl battery persist 75 80 stores specific values instead of the current ones. Many laptops, ThinkPads among them, remember the thresholds in firmware and don't need it. To remove it:

sudo systemctl disable --now laptopctl-battery.service
sudo rm /etc/systemd/system/laptopctl-battery.service
sudo systemctl daemon-reload

Keep awake

laptopctl awake on                 # stay awake until "awake off"
laptopctl awake on --for 90m       # ...for a duration (30m, 13h, 1h30m)
laptopctl awake on --until 17:30   # ...until a local time, 24-hour clock
laptopctl awake workday            # ...until 21:00 today (--end 22:30 to change)
laptopctl awake toggle             # on if off, off if on
laptopctl awake off
laptopctl awake                    # is it on, and for how much longer?

By default both the system and the display stay awake. Add --allow-display-sleep to let the screen blank and lock while the machine keeps running.

workday differs from --until in one way: started after the end time, it refuses instead of rolling over to tomorrow and holding the laptop awake for almost a day.

awake toggle makes a good keyboard shortcut: add it under Settings → Keyboard → View and Customize Shortcuts → Custom Shortcuts.

Screens

laptopctl screen off               # screens off until the next key press or mouse movement
laptopctl screen on                # bring them back, for example over SSH
laptopctl screen                   # are they on?

screen off waits for the keyboard and mouse to be still for a second, so the key that ran the command doesn't wake the screens straight away. It then stays running until you wake them; Ctrl+C turns them back on too.

To leave a long job running overnight with the screens dark:

laptopctl awake on --until 08:00
laptopctl screen off

Start awake first, because GNOME switches the screens back on when keep-awake begins.

Sensors

$ laptopctl sensors
coretemp
  Package id 0: 46.0°C
  Core 0: 45.0°C
  Core 1: 45.0°C
  Core 2: 46.0°C
  Core 3: 46.0°C

nvme
  Composite: 42.9°C
  Sensor 1: 42.9°C

thinkpad
  CPU: 44.0°C
  fan1: 2969 RPM

(Shortened. The real output lists every hwmon device.)

Updates

laptopctl version
laptopctl update --check           # is there a newer release?
laptopctl update                   # install it

update downloads the binary for your architecture from the latest GitHub release, checks it against the release's SHA256SUMS, runs it once to make sure it works on your machine, and only then swaps it in atomically. A failed update leaves the installed version untouched. laptopctl never checks for updates on its own; it only talks to the network when you run update.

The checksum is published next to the binary, so it guards against a corrupted download, not against a compromised release. Some commands run as root, so if you would rather not trust release binaries, build from source.

Requirements

Feature Needs
Battery status and health A battery under /sys/class/power_supply/BAT*
Charge thresholds A kernel driver that exposes charge_control_start_threshold and charge_control_end_threshold
Sensors hwmon sensors under /sys/class/hwmon
Keep awake A GNOME session
Screens GNOME on Mutter

When a battery doesn't expose the thresholds, laptopctl says so instead of failing silently; the charge limit may then be a BIOS setting. Developed and tested on a ThinkPad running Debian 13 with GNOME 48. Reports from other hardware are welcome.

How it works

No magic, and nothing that outlives its purpose:

  • Battery: reads and writes the kernel's power_supply files in sysfs.
  • Sensors: reads hwmon directly.
  • Keep awake: a small detached helper holds a GNOME SessionManager inhibitor over D-Bus and exits when the time is up or you run awake off. Its state lives in $XDG_RUNTIME_DIR/laptopctl.
  • Screens: sets Mutter's PowerSaveMode and watches Mutter's idle monitor for the first input.

Development

go test ./...
go vet ./...

The tests run against a fake sysfs tree and a local HTTP server, so they need neither a battery nor a network.

Pushing a tag such as v1.2.3 runs the release workflow, which builds the static binaries, writes SHA256SUMS and publishes the GitHub release that laptopctl update installs from.

A fork can ship its own updates by building with -ldflags "-X main.releaseURL=https://api.github.com/repos/OWNER/REPO/releases/latest".

License

Copyright © 2026 8ff

laptopctl is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It comes with no warranty. See LICENSE.

About

Battery charge thresholds, sensors, keep-awake and screens-off for Linux laptops, in one self-updating binary.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages