Mactop

Beautiful hardware monitoring for macOS with real-time metrics visualization.

Motivation

I created Mactop while learning about Metal programming for accelerating ML workloads on Apple Silicon. I wanted a terminal-based tool to monitor my mac's hardware usage in real-time while running GPU intensive tasks. There are existing tools that do the same but better, this was a fun exercise to dig into macOS internals, understanding the private APIs and terminal utilities that macOS provides.

Requirements

• macOS with Apple Silicon (M-series)
• Python 3.11+

Installation and Usage

You need uv installed on your system to run mactop.

# Clone the repository
git clone https://github.com/janaSunrise/mactop
cd mactop

# Install dependencies
uv sync

# Run (requires sudo)
sudo uv run python -m app

Why sudo? The powermetrics utility requires root access to collect system performance data.

How It Works

1. System Information Detection

On startup, Mactop queries your Mac's hardware configuration:

Chip name and CPU core counts using sysctl:

machdep.cpu.brand_string        # "Apple M1 Pro"

hw.ncpu                         # total cores
hw.perflevel0.physicalcpu       # performance cores
hw.perflevel1.physicalcpu       # efficiency cores

GPU core counts using system_profiler SPDisplaysDataType -detailLevel full:

Total Number of Cores: 14

2. Hardware Usage Metrics

Uses powermetrics to sample system state:

sudo powermetrics \
  --samplers cpu_power,gpu_power,ane_power,thermal \
  -n 1 \
  -i 500 \
  --format plist

Output includes:

• Per-cluster CPU frequency and idle ratios
• Per-core frequency and utilization
• GPU frequency and idle ratio
• Power consumption in milliwatts

License

MIT License - see LICENSE file for details.