agputop

Real-time GPU & CPU monitor for Apple Silicon — runs in your terminal.

---

Features

GPU utilization	Large percentage gauge with color-coded bar
CPU utilization	Per-interval average across all cores
Sparkline graphs	60-second scrolling history for GPU & CPU
Power breakdown	CPU / GPU / ANE watts, live bar chart
Thermal pressure	Nominal → Moderate → Heavy → Critical
System info	Chip name, GPU core count, RAM — shown in header
JSON output	--json flag for piping / scripting
No sudo (after install)	One-time sudoers entry grants passwordless powermetrics

---

Screenshots

Main view

High GPU load

JSON output

---

Requirements

• macOS 13 Ventura or later
• Apple Silicon Mac (M1 / M2 / M3 or later)
• Xcode Command Line Tools (xcode-select --install)

---

Installation

With Homebrew (Recommended)

brew tap hbasria/agputop https://github.com/hbasria/agputop
brew install agputop

To install by building from source temporarily:

brew install --build-from-source ./Formula/agputop.rb

After installation, follow the caveats instructions provided by Homebrew at the end of the process. This allows agputop to read real metrics without requiring sudo.

With Manual Script

To download the binary directly to your system (/usr/local/bin):

curl -fsSL https://raw.githubusercontent.com/hbasria/agputop/main/install.sh | bash

---

Developer (Build from source)

chmod +x build.sh
./build.sh

Running the App

# Real metrics (recommended)
sudo .build/release/agputop

# Demo mode (no sudo required)
.build/release/agputop

# Install system-wide manually
sudo cp .build/release/agputop /usr/local/bin/
sudo agputop

---

Usage

Interactive TUI (default)

agputop

Custom update interval

agputop --interval 2       # update every 2 seconds
agputop -i 0.5             # update every 500 ms

JSON streaming — pipe to other tools

# Pretty-print one sample
agputop --json | head -40

# Log to file
agputop --json >> metrics.jsonl

# Feed into jq — watch GPU watt in real time
agputop --json | jq -r '.gpu.power_w'

# Aggregate with mlr / awk
agputop --json --interval 5 | mlr --json stats1 -a mean -f gpu.utilization_pct

Example JSON output:

{
  "ane": { "power_w": 0.0 },
  "cpu": { "power_w": 3.21, "utilization_pct": 12.4 },
  "gpu": { "frequency_mhz": 798.0, "power_w": 1.43, "utilization_pct": 38.7 },
  "package": { "power_w": 5.86 },
  "system": {
    "chip": "Apple M3 Pro",
    "cpu_cores": 12,
    "gpu_cores": 18,
    "memory_gb": 36
  },
  "thermal_pressure": "Nominal",
  "timestamp": "2026-03-12T09:49:34Z"
}

Other flags

agputop --help
agputop --version

---

How it works

Layer	Technology
GPU / CPU metrics	powermetrics (Apple private SPI) via --samplers gpu_power,cpu_power,thermal
GPU core count	ioreg -c AGXAccelerator → gpu-core-count
Chip / RAM info	sysctl machdep.cpu.brand_string, hw.memsize
Terminal UI	Native ANSI / VT100 escape codes — no dependencies
Permissions	/etc/sudoers.d/agputop for passwordless powermetrics

powermetrics reads Apple Silicon's built-in performance counters. It reports true GPU active residency, frequency and power draw — not estimated values.

---

Controls

Key	Action
q	Quit
Ctrl-C	Quit

---

Compatibility

Chip	Tested
M1 / M1 Pro / M1 Max / M1 Ultra	✓
M2 / M2 Pro / M2 Max / M2 Ultra	✓
M3 / M3 Pro / M3 Max	✓
M4 / M4 Pro / M4 Max	Should work

---

Uninstall

sudo rm /usr/local/bin/agputop
sudo rm /etc/sudoers.d/agputop

---

License

MIT