{"id":13466647,"url":"https://github.com/actuallymentor/battery","last_synced_at":"2025-05-14T12:12:39.861Z","repository":{"id":37207096,"uuid":"452282568","full_name":"actuallymentor/battery","owner":"actuallymentor","description":"CLI/GUI for managing the battery charging status for Apple silicon (M1, M32, M3) Macs","archived":false,"fork":false,"pushed_at":"2024-08-14T09:19:22.000Z","size":3393,"stargazers_count":4594,"open_issues_count":119,"forks_count":200,"subscribers_count":38,"default_branch":"main","last_synced_at":"2025-04-30T08:44:31.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/actuallymentor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING","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}},"created_at":"2022-01-26T13:17:45.000Z","updated_at":"2025-04-30T07:37:21.000Z","dependencies_parsed_at":"2024-06-28T10:03:51.491Z","dependency_job_id":"304e4019-9d40-40f7-95d2-05714d0b394b","html_url":"https://github.com/actuallymentor/battery","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actuallymentor%2Fbattery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actuallymentor%2Fbattery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actuallymentor%2Fbattery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/actuallymentor%2Fbattery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/actuallymentor","download_url":"https://codeload.github.com/actuallymentor/battery/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140768,"owners_count":22021220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-07-31T15:00:47.684Z","updated_at":"2025-05-14T12:12:39.806Z","avatar_url":"https://github.com/actuallymentor.png","language":"JavaScript","funding_links":[],"categories":["Utilities","others","JavaScript","Shell","Uncategorized","Table of Contents"],"sub_categories":["Settings","Uncategorized","MacOS"],"readme":"# Battery charge limiter for Apple Silicon Macbook devices\n\n\u003cimg width=\"300px\" align=\"right\" src=\"./screenshots/tray.png\"/\u003eThis tool makes it possible to keep a chronically plugged in Apple Silicon Macbook at `80%` battery, since that will prolong the longevity of the battery. It is free and open-source and will remain that way.\n\n\u003e Want to know if this tool does anything or is just a placebo? Read [this excellent article](https://batteryuniversity.com/article/bu-808-how-to-prolong-lithium-based-batteries). TL;DR: keep your battery cool, keep it at 80% when plugged in, and discharge it as shallowly as feasible.\n\n### Requirements\n\nThis is an app for Apple Silicon Macs. It will not work on Intel macs. Do you have an older Mac? Consider the free version of the [Al Dente](https://apphousekitchen.com/) software package. It is a good alternative and has a premium version with many more features.\n\n### Installation\n\n- Option 1: install the app through brew with `brew install battery`\n- Option 2: [download the app dmg version here](https://github.com/actuallymentor/battery/releases/)\n- Option 3: install ONLY the command line interface (see section below)\n\nWhen installing via brew or dmg, opening the macOS app is required to complete the installation.\n\nThe first time you open the app, it will ask for your administator password so it can install the needed components. Please note that the app:\n\n- Discharges your battery until it reaches 80%, **even when plugged in**\n- Disables charging when your battery is above 80% charged\n- Enables charging when your battery is under 80% charged\n- Keeps the limit engaged even after rebooting\n- Keeps the limit engaged even after closing the tray app\n- Also automatically installs the `battery` command line tool. If you want a custom charging percentage, the CLI is the only way to do that.\n\nDo you have questions, comments, or feature requests? [Open an issue here](https://github.com/actuallymentor/battery/issues) or [Tweet at me](https://twitter.com/actuallymentor).\n\n---\n\n## 🖥 Command-line version\n\n\u003e If you don't know what a \"command line\" is, ignore this section. You don't need it.\n\nThe GUI app uses a command line tool under the hood. Installing the GUI automatically installs the CLI as well. You can also separately install the CLI.\n\nThe CLI is used for managing the battery charging status for Apple Silicon Macbooks. Can be used to enable/disable the Macbook from charging the battery when plugged into power.\n\n### Installation\n\nOne-line installation:\n\n```bash\ncurl -s https://raw.githubusercontent.com/actuallymentor/battery/main/setup.sh | bash\n```\n\nThis will:\n\n1. Download the precompiled `smc` tool in this repo (built from the [hholtmann/smcFanControl](https://github.com/hholtmann/smcFanControl.git) repository)\n2. Install `smc` to `/usr/local/bin`\n3. Install `battery` to `/usr/local/bin`\n\n### Usage\n\nExample usage:\n\n```shell\n# This will enable charging when your battery dips under 80, and disable it when it exceeds 80\nbattery maintain 80\n```\n\nAfter running a command like `battery charging off` you can verify the change visually by looking at the battery icon:\n\n![Battery not charging](./screenshots/not-charging-screenshot.png)\n\nAfter running `battery charging on` you will see it change to this:\n\n![Battery charging](./screenshots/charging-screenshot.png)\n\nFor help, run `battery` without parameters:\n\n```\nBattery CLI utility v1.0.1\n\nUsage:\n\n  battery status\n    output battery SMC status, % and time remaining\n\n  battery maintain LEVEL[1-100,stop]\n    reboot-persistent battery level maintenance: turn off charging above, and on below a certain value\n    eg: battery maintain 80\n    eg: battery maintain stop\n\n  battery charging SETTING[on/off]\n    manually set the battery to (not) charge\n    eg: battery charging on\n\n  battery adapter SETTING[on/off]\n    manually set the adapter to (not) charge even when plugged in\n    eg: battery adapter off\n\n  battery charge LEVEL[1-100]\n    charge the battery to a certain percentage, and disable charging when that percentage is reached\n    eg: battery charge 90\n\n  battery discharge LEVEL[1-100]\n    block power input from the adapter until battery falls to this level\n    eg: battery discharge 90\n\n  battery visudo\n    ensure you don't need to call battery with sudo\n    This is already used in the setup script, so you should't need it.\n\n  battery update\n    update the battery utility to the latest version\n\n  battery reinstall\n    reinstall the battery utility to the latest version (reruns the installation script)\n\n  battery uninstall\n    enable charging, remove the smc tool, and the battery script\n```\n\n## FAQ \u0026 Troubleshooting\n\n### Why does this exist?\n\nI was looking at the Al Dente software package for battery limiting, but I found the [license too limiting](https://github.com/davidwernhart/AlDente/discussions/558) for a poweruser like myself.\n\nI would actually have preferred using Al Dente, but decided to create a command-line utility to replace it as a side-project on holiday. A colleague mentioned they would like a GUI, so I spend a few evenings setting up an Electron app. And voila, here we are.\n\n### \"It's not working\"\n\nIf you used one of the earlier versions of the `battery` utility, you may run into [path/permission issues](https://github.com/actuallymentor/battery/issues/8). This is not your fault but mine. To fix it:\n\n```\nsudo rm -rf ~/.battery\nbinfolder=/usr/local/bin\nsudo rm -v \"$binfolder/smc\" \"$binfolder/battery\"\n```\n\nThen reopen the app and things should work. If not, [open an issue](https://github.com/actuallymentor/battery/issues/new/choose) and I'll try to help you fix it.\n\n### A note to Little Snitch users\n\nThis tool calls a number of urls, blocking all of them will only break auto-updates.\n\n1. `unidentifiedanalytics.web.app` is a self-made app that tracks app installations, I use it to see if enough people use the app to justify spending time on it. It tracks only how many unique ip addresses open the app.\n1. `icanhazip.com` is used to see if there is an internet connection\n1. `github.com` is used both as a liveness check and as the source of updates for the underlying command-line utility\n1. `electronjs.org` hosts the update server for the GUI\n\nAll urls are called over `https` and so not leak data. Unidentified Analytics keeps track of unique ip addresses that open the app, but nothing else.\n\n### What distinguishes this project from Optimized Charging?\n\nOptimized Charging, a feature that is built into MacOS, aims to ensure the longevity and health of your battery. It does so by \"delaying charging the battery past 80% when it predicts that you’ll be plugged in for an extended period of time, and aims to charge the battery before you unplug,\" as explained in [Apple's user guide](https://support.apple.com/en-ca/guide/mac-help/mchlfc3b7879/mac#:~:text=Optimized%20Battery%20Charging%3A%20To%20reduce,the%20battery%20before%20you%20unplug.).\n\nAdditionally, Optimized Charging uses machine learning to decide when the battery should be held at 80%, and when it should become fully charged. If your Mac is not plugged in on a regular schedule, optimized charging will not work as intended.\n\nThis app is a similar alternative to Optimized Charging, giving the user control over when it is activated, what percentage the battery should be held at, and more.\n\n### How do I support this project?\n\nDo you know how to code? Open a pull-request for a feature with the label [help wanted (PR welcome)](https://github.com/actuallymentor/battery/labels/help%20wanted%20%28PR%20welcome%29).\n\nDo you have an awesome feature idea? [Add a feature request](https://github.com/actuallymentor/battery/issues/new/choose)\n\nDo you just want to keep me motivated to update the app? [Tweet at me](https://twitter.com/actuallymentor)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factuallymentor%2Fbattery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Factuallymentor%2Fbattery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Factuallymentor%2Fbattery/lists"}