https://github.com/dbackowski/battery-menubar
A lightweight macOS menu bar application that displays battery status, remaining time, and detailed battery health information.
https://github.com/dbackowski/battery-menubar
Last synced: 5 months ago
JSON representation
A lightweight macOS menu bar application that displays battery status, remaining time, and detailed battery health information.
- Host: GitHub
- URL: https://github.com/dbackowski/battery-menubar
- Owner: dbackowski
- Created: 2026-01-10T16:49:12.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-11T10:51:12.000Z (5 months ago)
- Last Synced: 2026-01-11T15:32:50.500Z (5 months ago)
- Language: Swift
- Homepage:
- Size: 10.2 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Battery Menu Bar
A lightweight macOS menu bar application that displays battery status, remaining time, and detailed battery health information.
## Features
- **Real-time Battery Status**: Shows current battery percentage and time remaining/charging in the menu bar
- **Detailed Information**: Click to view:
- Battery capacity (current vs. design capacity in mAh)
- Battery health percentage
- Cycle count
- Estimated time remaining (when on battery)
- Estimated time to full charge (when charging)
- **Lightweight**: Minimal resource usage, updates every 30 seconds
- **Menu Bar Only**: No dock icon, stays out of your way
## Screenshots
### Menu Bar Display
- **On Battery**: 🔋 85% 2:34
- **Charging**: âš¡ 65% 1:23
- **Fully Charged**: âš¡ 100%
### Dropdown Menu
```
Battery: 85% - 2h 34m remaining
─────────────────────────────────
Capacity: 4200 mAh / 4382 mAh (96%)
Cycle Count: 245
─────────────────────────────────
Quit ⌘Q
```
## Installation
### Pre-built App (Easy)
1. Download the latest `BatteryMenuBar.app.zip` from [Releases](https://github.com/dbackowski/battery-menubar/releases)
2. Unzip and drag `BatteryMenuBar.app` to your Applications folder
3. Open the app
4. If macOS blocks it (unidentified developer), go to System Preferences → Security & Privacy → General and click "Open Anyway"
### Build from Source
#### Requirements
- macOS 10.15 (Catalina) or later
- Xcode Command Line Tools
#### Steps
1. **Install Command Line Tools** (if not already installed):
```bash
xcode-select --install
```
2. **Clone the repository**:
```bash
git clone https://github.com/dbackowski/battery-menubar.git
cd battery-menubar
```
3. **Build the app**:
```bash
chmod +x build_with_icon.sh
./build_with_icon.sh
```
4. **Install to Applications**:
```bash
cp -r BatteryMenuBar.app /Applications/
```
5. **Run**:
```bash
open /Applications/BatteryMenuBar.app
```
## Manual Build (Without Script)
If you prefer to build manually:
```bash
# Compile
swiftc main.swift -o BatteryMenuBar -framework Cocoa -framework IOKit
# Create app bundle
mkdir -p BatteryMenuBar.app/Contents/MacOS
mkdir -p BatteryMenuBar.app/Contents/Resources
# Move executable
mv BatteryMenuBar BatteryMenuBar.app/Contents/MacOS/
# Copy Info.plist
cp Info.plist BatteryMenuBar.app/Contents/
# (Optional) Add icon
cp icon.icns BatteryMenuBar.app/Contents/Resources/AppIcon.icns
# Run
open BatteryMenuBar.app
```
## Usage
### Starting the App
- Double-click `BatteryMenuBar.app` in your Applications folder
- The battery icon will appear in your menu bar
### Making it Start on Login
1. Open **System Preferences** → **Users & Groups** → **Login Items**
2. Click the **+** button
3. Select `BatteryMenuBar.app` from Applications
4. Check the "Hide" checkbox to start it minimized
### Quitting the App
- Click the battery icon in the menu bar
- Select **Quit** or press **⌘Q**
## Information Displayed
| Item | Description |
|------|-------------|
| **Menu Bar Icon** | Battery emoji (🔋 on battery, ⚡ when charging) |
| **Percentage** | Current battery charge level |
| **Time** | Time remaining on battery or time until full charge |
| **Capacity** | Current maximum capacity vs. original design capacity |
| **Health %** | Battery health as percentage of original capacity |
| **Cycle Count** | Number of complete charge cycles |
## Technical Details
- **Language**: Swift
- **Frameworks**: Cocoa, IOKit
- **Update Interval**: 30 seconds
- **Permissions**: None required (uses public system APIs)
- **Architecture**: Universal (Intel and Apple Silicon)
## File Structure
```
battery-menubar/
├── main.swift # Main application code
├── Info.plist # App bundle information
├── build_with_icon.sh # Build script with icon generation
├── icon.png # Generated app icon (1024x1024)
├── icon.icns # macOS icon format
└── README.md # This file
```
## Troubleshooting
### App won't open - "Unidentified Developer"
macOS Gatekeeper blocks unsigned apps by default:
1. Go to **System Preferences** → **Security & Privacy** → **General**
2. Click **Open Anyway** next to the blocked app message
3. Confirm by clicking **Open**
Alternatively, right-click the app and select **Open**, then click **Open** in the dialog.
### Battery information shows "Unable to read"
This is rare but can happen if:
- Your Mac doesn't have a battery (desktop Mac)
- Battery information APIs are restricted (unlikely)
- The system needs a restart
Try restarting your Mac and reopening the app.
### Time remaining shows "Calculating..."
macOS needs a few minutes of usage data to estimate battery time accurately. This is normal when:
- You just started using your Mac
- You just unplugged/plugged in the charger
- Battery usage pattern changed significantly
Wait a few minutes and it should update.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
Released under the MIT License.
## Acknowledgments
- Built with native macOS APIs (Cocoa and IOKit)
- Inspired by the need for a simple, lightweight battery monitor
## Support
If you encounter any issues or have questions:
- Open an [Issue](https://github.com/dbackowski/battery-menubar/issues)
- Check existing issues for solutions
- Pull requests are welcome!