Mac Manager

Monitor your Mac's health, security and hardware from the terminal — battery alerts, live dashboard, security audit and dev-tooling inventory.

A Python CLI to monitor and take care of your MacBook (Apple Silicon) right from the terminal — battery, system, disk, network — with a live dashboard, automatic daily logging, and native notifications to preserve battery health.

Designed for Apple Silicon MacBook Air/Pro. It also works on Intel, but some metrics (battery capacity, etc.) may vary.

Installation

Homebrew (recommended)

brew install armelingu/tap/mac-manager

The formula lives at armelingu/homebrew-tap. You can also brew install --HEAD armelingu/tap/mac-manager to track the latest commit on main instead of the released version.

pipx / pip

pipx install mac-manager   # isolated, recommended
# or
pip install --user mac-manager

After installation, the mm command is on your PATH. Register the background agents (daily battery log + alerts) with:

mm setup

mm uninstall removes those agents. It does not uninstall the CLI — use brew uninstall mac-manager or pipx uninstall mac-manager for that.

From source

git clone https://github.com/armelingu/mac-manager.git
cd mac-manager
./install.sh

This will:

• create a local venv in .venv/
• install rich and psutil
• create the symlink ~/.local/bin/mm
• register two launchd agents:
  • daily log at 09:00 → writes a snapshot to ~/Library/Application Support/mac-manager/battery.csv
  • battery alerts every 15 min → native macOS notification

Make sure ~/.local/bin is in your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Commands

For the complete reference for each command (description, options, when to use, examples), see COMMANDS.md.

Hardware and system

Battery — history

Setup

Security

Development

Smart alerts

To preserve the lithium-ion battery (every cycle counts!), the agent checks every 15 min and fires a notification:

• ≥ 80% charging → "consider unplugging" (every 2h)
• ≤ 20% on battery → "good time to plug in" (every 30min)
• ≤ 10% on battery → critical alert (every 10min)
• health < 80% → 1x per week

History

Every day at 9 AM, a snapshot is written to ~/Library/Application Support/mac-manager/battery.csv:

timestamp,percent,is_charging,power_source,cycle_count,max_capacity_mah,design_capacity_mah,health_percent,temperature_c
2026-04-19T09:00:01,82,1,AC Power,12,4350,4380,99.3,30.5

In a few months you can plot the real degradation of your Mac.

Structure

mac-manager/
├── mm                      # entrypoint (bash → venv python)
├── macmanager/
│   ├── cli.py              # dispatcher
│   ├── ui.py               # UI helpers
│   ├── battery.py          # ioreg + pmset
│   ├── system.py           # CPU/RAM/processes via psutil
│   ├── disk.py             # usage + snapshots + cleanup
│   ├── network.py          # Wi-Fi + IPs
│   ├── notify.py           # osascript notifications
│   ├── logger.py           # CSV history
│   ├── doctor.py           # score + tips
│   ├── alerts.py           # notification rules
│   ├── security.py         # security audit (mm security)
│   ├── dev.py              # dev tooling inventory (mm dev)
│   └── watch.py            # live dashboard
├── launchd/
│   ├── com.macmanager.battery-log.plist
│   └── com.macmanager.battery-alert.plist
├── logs/
├── install.sh
├── uninstall.sh
└── requirements.txt

Uninstallation

mm uninstall          # launchd agents only (Homebrew / pipx / source)
./uninstall.sh        # source install: agents + symlink + venv

mm uninstall does not remove the CLI. For packaged installs:

brew uninstall mac-manager
# or
pipx uninstall mac-manager

Battery history in ~/Library/Application Support/mac-manager/ is preserved.

Status

Mac Manager is currently in alpha: the public CLI surface is stabilizing, breaking changes can still happen between 0.x releases without a deprecation window. Once we ship 1.0.0, every breaking change will follow Semantic Versioning and a deprecation cycle.

Changelog

All notable changes are documented in CHANGELOG.md, following the Keep a Changelog format.

Releasing

Maintainers: see RELEASING.md for the full release runbook (SemVer policy, version bump, tagging and the tag-driven GitHub Actions pipeline that builds artifacts and cuts a GitHub Release automatically — PyPI publication is wired with Trusted Publishing and can be activated by flipping a single flag).

Contributing

Contributions are very welcome — whether it's a bug report, a feature request or a pull request. Please read the contribution guide before opening anything:

• 📖 CONTRIBUTING.md — how to set up a dev environment, coding style, commit conventions and PR workflow.
• 🛡️ SECURITY.md — how to responsibly report a vulnerability.
• 🤝 CODE_OF_CONDUCT.md — what we expect from everyone participating in this project.

The files above are being added incrementally; until each one lands, please open an issue on GitHub for anything you'd like to discuss.

License

Copyright © 2026 Gustavo Armelin.

This project is released under the Apache License 2.0 — a permissive license that allows commercial use, modification, distribution and private use, with patent protection. See NOTICE for the required attribution and the third-party licenses bundled at runtime.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0