{"id":46585184,"url":"https://github.com/ooooze/batctl","last_synced_at":"2026-03-13T21:01:38.550Z","repository":{"id":342772397,"uuid":"1175121714","full_name":"Ooooze/batctl","owner":"Ooooze","description":"⚡ Battery charge threshold manager for Linux laptops","archived":false,"fork":false,"pushed_at":"2026-03-11T17:47:52.000Z","size":8886,"stargazers_count":100,"open_issues_count":6,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-13T00:52:46.148Z","etag":null,"topics":["battery","charge-threshold","cli","go","laptop","linux","power-management","terminal","thinkpad","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ooooze.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-07T09:00:12.000Z","updated_at":"2026-03-12T22:41:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Ooooze/batctl","commit_stats":null,"previous_names":["ooooze/batctl"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/Ooooze/batctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ooooze%2Fbatctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ooooze%2Fbatctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ooooze%2Fbatctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ooooze%2Fbatctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ooooze","download_url":"https://codeload.github.com/Ooooze/batctl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ooooze%2Fbatctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30475616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T20:45:58.186Z","status":"ssl_error","status_checked_at":"2026-03-13T20:45:20.133Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["battery","charge-threshold","cli","go","laptop","linux","power-management","terminal","thinkpad","tui"],"created_at":"2026-03-07T12:04:04.262Z","updated_at":"2026-03-13T21:01:38.544Z","avatar_url":"https://github.com/Ooooze.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e⚡ batctl\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eBattery charge threshold manager for Linux laptops\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n    \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n    \u003ca href=\"#supported-hardware\"\u003eHardware\u003c/a\u003e •\n    \u003ca href=\"#presets\"\u003ePresets\u003c/a\u003e •\n    \u003ca href=\"#persistence\"\u003ePersistence\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\n**batctl** is a terminal UI and CLI tool that lets you control battery charge thresholds on Linux.\nSet start/stop charge levels to extend battery lifespan, choose from built-in presets,\nand persist your settings across reboots — all from a single, zero-dependency binary.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"demo.gif\" alt=\"batctl demo\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Why batctl?\n\nMost laptops support charge thresholds in hardware, but the Linux interface is fragmented:\neach vendor exposes different sysfs paths, value ranges, and quirks.\nTools like TLP are powerful but heavy and config-file-driven.\n\n**batctl** gives you:\n\n- **One binary, zero config** — auto-detects your hardware and shows what's possible\n- **Interactive TUI** — see battery health, adjust thresholds with arrow keys, pick presets\n- **Scriptable CLI** — `batctl set --stop 80` for automation and dotfiles\n- **16+ vendor backends** — from ThinkPad to Apple Silicon, with a generic fallback\n- **Persistence** — survives reboots and suspend/resume via systemd\n\n## Installation\n\n### Quick install (any distro)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Ooooze/batctl/master/install.sh | sudo bash\n```\n\nTo uninstall:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Ooooze/batctl/master/install.sh | sudo bash -s -- --uninstall\n```\n\n### From source\n\n```bash\ngit clone https://github.com/Ooooze/batctl.git\ncd batctl\nmake\nsudo make install\n```\n\n### Arch Linux / Omarchy (AUR)\n\n```bash\nyay -S batctl-tui\n```\n\nOr manually:\n\n```bash\nmakepkg -si\n```\n\n### Pre-built binary\n\nDownload from [Releases](https://github.com/Ooooze/batctl/releases), then:\n\n```bash\nchmod +x batctl\nsudo cp batctl /usr/bin/\n```\n\n## Usage\n\n### Interactive TUI\n\nLaunch the full terminal interface (requires root for write operations):\n\n```bash\nsudo batctl\n```\n\n**Controls:**\n\n| Key | Action |\n|-----|--------|\n| `↑` `↓` / `j` `k` | Navigate between fields |\n| `←` `→` / `h` `l` | Adjust value (±1) |\n| `H` `L` | Adjust value (±5) |\n| `Enter` | Toggle edit mode |\n| `Esc` | Cancel edit |\n| `p` | Open preset picker |\n| `a` | Apply current thresholds |\n| `s` | Save config + enable persistence |\n| `r` | Refresh battery info |\n| `q` | Quit |\n\n### CLI Commands\n\n```bash\n# Show battery info, thresholds, and persistence status\nbatctl status\n\n# Detect hardware and show capabilities\nbatctl detect\n\n# Set thresholds directly\nsudo batctl set --start 40 --stop 80\n\n# Apply a built-in preset\nsudo batctl set --preset max-lifespan\n\n# Apply thresholds from config (used by systemd on boot)\nsudo batctl apply\n\n# Enable persistence (systemd services: boot + resume)\nsudo batctl persist enable\n\n# Check persistence status\nbatctl persist status\n\n# Disable persistence and clean up\nsudo batctl persist disable\n```\n\n### Example: `batctl status`\n\n```\nBackend: ThinkPad\n\nBAT0 (Sunwoda 5B10W51867)\n  Status:     Charging\n  Capacity:   85%\n  Health:     103.6%\n  Cycles:     54\n  Energy:     48.3 / 52.8 Wh (design: 51.0 Wh)\n  Power:      20.1 W\n  Thresholds: start=40% stop=80%\n  Behaviour:  auto (available: auto, inhibit-charge, force-discharge)\n\nPersistence:  boot=true  resume=true\n```\n\n### Example: `batctl detect`\n\n```\nVendor:  LENOVO\nProduct: 21AH00FGRT\nBackend: ThinkPad\nCapabilities:\n  Start threshold:    true (range: 0..99)\n  Stop threshold:     true (range: 1..100)\n  Charge behaviour:   true\nBatteries: [BAT0]\n```\n\n## Presets\n\nBuilt-in presets adapt automatically to your hardware's supported value ranges:\n\n| Preset | Start | Stop | Description |\n|--------|------:|-----:|-------------|\n| `max-lifespan` | 20% | 80% | Best for battery longevity. Ideal if you're mostly plugged in. |\n| `balanced` | 40% | 80% | Good mix of available capacity and long-term health. |\n| `plugged-in` | 70% | 80% | Narrow band for always-connected workstations. |\n| `full-charge` | 0% | 100% | No restrictions. Use when you need maximum runtime. |\n\n```bash\nsudo batctl set --preset balanced\n```\n\n\u003e On hardware with limited options (e.g. Samsung with only 80/100),\n\u003e presets snap to the nearest supported value.\n\n## Supported Hardware\n\nbatctl auto-detects your laptop vendor via DMI and probes sysfs for the right driver.\nIf no specific backend matches, the **generic fallback** is used for any laptop\nexposing standard `charge_control_{start,end}_threshold` files.\n\n| Vendor | Start | Stop | Behaviour | Kernel Driver |\n|--------|:-----:|:----:|:---------:|---------------|\n| **Acer** | — | 80 or 100 | — | `acer-wmi-battery` |\n| **Lenovo ThinkPad** | 0–99 | 1–100 | ✓ | `thinkpad_acpi` |\n| **ASUS** | — | 0–100¹ | — | `asus_wmi` |\n| **Dell** | 50–95 | 55–100 | — | `dell_laptop` |\n| **Lenovo IdeaPad** | — | on/off² | — | `ideapad_laptop` |\n| **Huawei MateBook** | 0–99 | 1–100 | — | `huawei_wmi` |\n| **Samsung** | — | 80 or 100 | — | `samsung_laptop` |\n| **LG Gram** | — | 80 or 100 | — | `lg_laptop` |\n| **MSI** | auto³ | 10–100 | — | `msi_ec` |\n| **Framework** | 0–99⁴ | 1–100 | ✓ | `cros_charge-control` |\n| **System76** | 0–99 | 1–100 | — | `system76_acpi` |\n| **Sony VAIO** | — | 50/80/100 | — | `sony_laptop` |\n| **Toshiba/Dynabook** | — | 80 or 100 | — | `toshiba_acpi` |\n| **Tuxedo (Clevo)** | discrete⁵ | discrete⁵ | — | `clevo_acpi` |\n| **Apple Silicon** | auto³ | 80 or 100 | — | `macsmc_power` |\n| **Microsoft Surface** | 0–99⁶ | 1–100 | — | `surface_battery` |\n| **Generic fallback** | 0–99 | 1–100 | ✓ | any sysfs |\n\n\u003csup\u003e¹ Some ASUS models only accept 40, 60, or 80\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e² Conservation mode: fixed threshold (usually 60%)\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e³ Start threshold is computed by hardware from stop value\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e⁴ Start threshold requires EC firmware v3\u003c/sup\u003e\u003cbr\u003e\n\u003csup\u003e⁵ Tuxedo start: 40/50/60/70/80/95 — stop: 60/70/80/90/100\u003c/sup\u003e\n\u003csup\u003e⁶ Requires linux-surface kernel; start threshold availability varies by model\u003c/sup\u003e\n\n## Persistence\n\nBy default, charge thresholds reset on reboot or resume from suspend.\nbatctl solves this with a one-command setup:\n\n```bash\nsudo batctl persist enable\n```\n\nThis installs:\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| Config file | `/etc/batctl.conf` | Stores your threshold values |\n| Boot service | `/etc/systemd/system/batctl.service` | Applies thresholds on boot |\n| Resume service | `/etc/systemd/system/batctl-resume.service` | Restores thresholds after suspend/resume |\n\nTo disable and remove everything:\n\n```bash\nsudo batctl persist disable\n```\n\n## How It Works\n\n```\nbatctl\n├── Reads /sys/class/dmi/id/sys_vendor → identifies laptop vendor\n├── Probes sysfs paths → confirms driver availability\n├── Selects matching backend (or generic fallback)\n├── Reads/writes /sys/class/power_supply/BAT*/charge_control_*\n└── Manages systemd services for persistence\n```\n\nAll operations go through the kernel's standard sysfs interface.\nNo direct hardware access, no custom kernel modules required.\n\n## Architecture\n\n```\nbatctl/\n├── cmd/batctl/          → CLI entry point (cobra)\n├── internal/\n│   ├── backend/         → 16 vendor backends + generic + auto-detection\n│   ├── battery/         → sysfs read/write helpers, battery info\n│   ├── persist/         → systemd services, config file\n│   ├── preset/          → built-in presets with hardware adaptation\n│   └── tui/             → bubbletea TUI (dashboard, presets, styles)\n├── configs/             → systemd service templates\n├── Makefile\n└── PKGBUILD             → Arch Linux package\n```\n\n## Requirements\n\n- **Linux** with a kernel that includes your laptop's battery driver\n- **Root access** (`sudo`) for writing thresholds and managing persistence\n- No runtime dependencies — single static binary\n\n## Community Projects\n\n\n- **[threshpad](https://github.com/looselyhuman/threshpad)** — GNOME Shell extension for batctl\n\n## Contributing\n\nContributions are welcome! Areas where help is especially appreciated:\n\n- **New vendor backends** — if your laptop isn't detected, check `batctl detect` output and open a PR\n- **Testing** — try batctl on your hardware and report what works\n- **Packaging** — help with Fedora, Debian, NixOS packages\n\n## Donate\n\nIf batctl saved your battery some cycles, consider buying me a coffee in crypto:\n\n| Currency | Network | Address |\n|----------|---------|---------|\n| **BTC** | Bitcoin | `bc1qflyxz75wkcyet89cttanyv7ws98lf8wjezdydq` |\n| **ETH** | Ethereum | `0xAfAA1CEdb10ECfC696C9984e857c813CB1871b4C` |\n| **USDT** | TRC-20 | `TSgwHUf6tiuJgFmaerb3TyTjggoP5cPecb` |\n| **TON** | TON | `UQA1SYTIdmH7iPNcUtbOtQXtCLPzTYeR8YxCdxksU8HMhkSe` |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooooze%2Fbatctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fooooze%2Fbatctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fooooze%2Fbatctl/lists"}