chargestat
Mac power adapter, charge rate, and time to full/empty in the terminal. Read-only, no sudo, no dependencies beyond the Python standard library.
Adapter 100 W · pd charger · 20.0 V × 5.00 A negotiated
PDOs 5V 3A · 9V 3A · 15V 3A · [20V 5A]
Status Charging 23% █████░░░░░░░░░░░░░░░
Rate +476 mA · +9.0 %/h
Time 10h 14m to full (macOS)
Power ~14.0 W in → 8.8 W system, +5.3 W battery · ~14.9 W at wall
Battery 1169/5312 mAh · 11.44 V · 30.6 °C
Health 85% of design (6249 mAh) · 437 cycles
Updated 9 s ago by battery gauge
Install
Requires macOS. Homebrew provides Python; with uv, any Python ≥ 3.10 works.
| Homebrew | uv | pipx | |
|---|---|---|---|
| Install | brew install tjdcs/tap/chargestat |
uv tool install chargestat |
pipx install chargestat |
| Upgrade | brew upgrade chargestat |
uv tool upgrade chargestat |
pipx upgrade chargestat |
| Uninstall | brew uninstall chargestat |
uv tool uninstall chargestat |
pipx uninstall chargestat |
To try it without installing, run uvx chargestat. Add --refresh to pick up a new release.
Check the installed version with chargestat -V. CHANGELOG.md lists CLI and install changes for each release.
Usage
chargestat # one snapshot
chargestat -w # live view, refresh every 2 s (Ctrl-C to stop)
chargestat -w 5 -n 12 # 12 refreshes, 5 s apart
chargestat --json # machine-readable; with -w, one JSON object per line
chargestat -H # plot charge and battery power over the last 24 h
chargestat -H 6 # ... over the last 6 h (system powerlog keeps ~2-3 days)
Exit status is 2 when the Mac has no battery.
What the rows mean
| Row | Source (ioreg -rn AppleSmartBattery) |
Notes |
|---|---|---|
| Adapter | AdapterDetails |
Negotiated USB-PD contract, not live draw. |
| PDOs | AdapterDetails.UsbHvcMenu |
Fixed-supply PDOs the charger advertises; [ ] marks the active one. |
| Rate | InstantAmperage, AppleRawMaxCapacity |
Gauge current into (+) or out of (−) the pack, and the resulting SoC change per hour. |
| Time | AvgTimeToFull/AvgTimeToEmpty; mAh ÷ mA |
macOS's estimate, plus a linear estimate at the present current. The linear one ignores the constant-voltage taper, so it reads short near full. |
| Power | PowerTelemetryData |
Estimates (~). Input = system load + battery branch; "at wall" adds the reported adapter efficiency loss. |
| Battery / Health | AppleRawCurrentCapacity, DesignCapacity, CycleCount |
Health is full-charge capacity ÷ design capacity. |
| Updated | UpdateTime |
The gauge refreshes every ~15–60 s, so consecutive samples often repeat. |
NotChargingReason / SlowChargingReason are shown as raw hex because Apple doesn't document the bits.
Tested on Apple silicon. Intel Macs report capacities in mAh directly; that path is handled but untested on hardware.
Similar tools
- WhatBattery — menu bar app with a CLI; reads live power from SMC; some details require a paid tier.
- macbattery — terminal dashboard/TUI over IOKit.
- powermon — terminal power monitor parsing
ioregtext. - batt, battery, Battery Toolkit — charge control (limits, adapter on/off) rather than monitoring.
chargestat focuses on the adapter contract (PDOs), charge rate, and time estimates in a single read-only command that is easy to script.
Development
uv run chargestat
uv run pytest
uv run ruff check . && uv run ruff format --check .
See RELEASING.md for the PyPI and Homebrew release process.
1 maintainer
Metadata
1 maintainer
Release files for chargestat 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chargestat-0.1.1.tar.gz | 14.9 kB | Without provenance | Details for chargestat-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chargestat-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for chargestat-0.1.1-py3-none-any.whl |
Total release size: 31.0 kB
Release files / chargestat-0.1.1.tar.gz
| Download URL | chargestat-0.1.1.tar.gz |
|---|---|
| Size | 14.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4d93de7655ccea1d2c8e090d457f8a9a430bc44267d43ea5f9b188ae15569ade
|
|
BLAKE2b-256 checksum How to use checksums |
14fed0b1d55970276e0ebb366ece7dc3d39742e4caf602af19632e954af21118
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / chargestat-0.1.1-py3-none-any.whl
| Download URL | chargestat-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7e78f8c6bbff60e3c3e7929b23460ea3e63dce5fc6ad0cd5acca0c601b22929a
|
|
BLAKE2b-256 checksum How to use checksums |
6c62c45f0e5bf37a944d6096c1d06d7b58db55afa2800c3cf29eea7272523d00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for chargestat 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
