MacMonitor

A lightweight macOS menu bar application for real-time system monitoring.

MacMonitor lives in your menu bar and shows live CPU and memory usage at a glance. It uses native macOS APIs — vm_stat, sysctl, and the UserNotifications framework — for accurate, low-overhead telemetry with no background daemon required.

Python 3.9+ macOS 12+ MIT License v1.0.0

Capabilities

Native Menu Bar UI

The title updates every 5 seconds: C:XX% M:XX%. When pressure or usage is elevated, it switches to WARN, HIGH, or STRESS prefix automatically. No app window, no Dock icon.

Memory Breakdown

Reads vm_stat and memory_pressure to decompose RAM into four categories: Wired, Active, Compressed, and Cached. Flags lag risk when Compressed memory exceeds Active.

Process Intelligence

Top 5 CPU and memory consumers listed in real time. Kill any process directly from the dropdown without opening Activity Monitor. Chrome, Electron, Slack, and Discord are auto-tagged as GPU-heavy.

Native Alerts

Threshold breaches trigger UserNotifications alerts — the same system used by Calendar and Mail. Alerts use a stable identifier so they replace each other in-place rather than stacking. 120-second cooldown per metric.

Installation

Requires Python 3.9+ and macOS 12 Monterey or later.

1. Clone

$ git clone https://github.com/dinexh/Monarx.git MacMonitor
$ cd MacMonitor

2. Virtual environment

$ python3 -m venv .venv
$ source .venv/bin/activate

3. Dependencies

$ pip install -r requirements.txt

Installs: psutil · rumps · pyobjc-framework-Cocoa · pyobjc-framework-UserNotifications · pytest

Usage

$ python main.py

MacMonitor appears in your menu bar immediately as C:XX% M:XX%. Click it to open the dropdown.

Menu bar states

C:43% M:71% All metrics within configured thresholds

WARN C:58% M:74% Memory pressure at WARN level

HIGH C:91% M:83% Memory pressure is HIGH

STRESS C:35% M:76% Compressed memory exceeds Active (lag risk)

Configuration

Change thresholds at runtime via Settings → Change Thresholds in the dropdown, or edit core/config.py directly. Values persist in ~/Library/Application Support/MacMonitor/config.json.

Click a row to see details.

Auto-Start on Login

Create a LaunchAgent plist to start MacMonitor automatically at login. Replace /path/to/MacMonitor with your actual clone path.

1. Create the plist

$ nano ~/Library/LaunchAgents/com.macmonitor.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.macmonitor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/MacMonitor/.venv/bin/python</string>
        <string>/path/to/MacMonitor/main.py</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/MacMonitor</string>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
</dict>
</plist>

2. Load the agent

$ launchctl load ~/Library/LaunchAgents/com.macmonitor.plist

Unload

$ launchctl unload ~/Library/LaunchAgents/com.macmonitor.plist

Log files

MacMonitor writes logs to ~/Library/Logs/MacMonitor/macmonitor.log. Open them from the menu via View Logs.