mactop

mactop is a terminal-based monitoring tool "top" designed to display real-time metrics for Apple Silicon chips written by Carsen Klock. It provides a simple and efficient way to monitor CPU and GPU usage, E-Cores and P-Cores, power consumption, GPU frequency, temperatures, and other system metrics directly from your terminal

Compatibility

• Apple Silicon Only (ARM64)
• macOS Monterey 12.3+

Features

• No sudo required - Uses native Apple APIs (SMC, IOReport, IOKit, IOHIDEventSystemClient)
• Apple Silicon Monitor Top written in Go Lang and CGO
• Real-time CPU, GPU, ANE, DRAM, and system power wattage usage display
• GPU frequency and usage percentage display
• CPU and GPU temperatures + Thermal State
• M5 Super Core (S-Core) Support: Full support for Apple M5's new CPU architecture (E-cores, P-cores, S-cores)
• DRAM Bandwidth Monitoring: Real-time DRAM read/write bandwidth (GB/s) — uses auto-calibrated power-based estimation on M5+ chips (no sudo required)
• Comprehensive Temperature Sensors: All available SMC temperature sensors (CPU Die, GPU, Memory, SSD, Airflow, and more) with human-readable labels
• Fan Monitoring: Real-time fan RPM, target speed, mode (Auto/Manual), and visual RPM bars
• Fan Speed Control: Optional interactive fan speed control via --fan-control flag (writes to SMC)
• Detailed native metrics for CPU cores (E-cores, P-cores, and S-cores on M5+) via Apple's Mach Kernel API
• Memory usage and swap information
• Network usage information (upload/download speeds)
• Thunderbolt bandwidth monitoring: Real-time throughput for Thunderbolt Bridge interfaces
• Thunderbolt Device Tree: Visual tree of connected Thunderbolt/USB4 devices and their speeds
• RDMA Support: Detection of RDMA over Thunderbolt 5 availability
• Disk I/O activity (read/write speeds)
• Proportional per process GPU usage (experimental)
• Multiple volume display (shows Mac HD + mounted external volumes)
• Easy-to-read terminal UI
• 18 Layouts: (l to cycle layouts)
• Persistent Settings: Remembers your Layout and Theme choice across restarts
• Customizable UI color (green, red, blue, skyblue, magenta, yellow, gold, silver, white, lime, orange, violet, pink, and more) (c to cycle colors)
• Customizable background color (b to cycle colors)
• Customizable update interval (default is 1000ms) (- or = to speed up, + to slow down)
• Process list matching htop format (VIRT in GB, CPU normalized by core count)
• Process Management: Kill processes directly from the UI (F9) with safe confirmation.
• Process Filter: Search and filter processes by name (/)
• Navigation: Enhanced Vim-like navigation (g top, G bottom, j/k scroll)
• Headless Mode: Output JSON metrics to stdout for scripting/logging (--headless)
• JSON Formatting: Pretty print JSON output (--pretty) or set collection count (--count <n>)
• Output Formats: JSON (default), YAML, XML, CSV, and TOON (--format <format>)
• Freeze: Pause/Resume process list updates (f)
• Party Mode (Randomly cycles through colors) (p to toggle)
• Optional Prometheus Metrics server (default is disabled) (-p <port> or --prometheus <port>)
  • Exports: CPU/GPU/ANE usage, E/P/S-core averages, per-core usage (labeled by type), power components, DRAM bandwidth (read/write/combined), memory, network, disk, fan RPM, temperature sensors, thermal state, and more
• macOS Menu Bar Mode: Run as a native menu bar status item (--menubar) with sparkline charts, CPU/GPU/Memory gauges, power metrics, DRAM bandwidth, fan RPM, and full system stats
• Support for all Apple Silicon models
• Auto-detect Light/Dark Mode: Automatically adjusts UI colors based on your terminal's background color or system theme.
• Configurable Units: Customize units for network, disk, and temperature display (--unit-network, --unit-disk, --unit-temp)

Install via Homebrew

You can install mactop via Homebrew! https://brew.sh

brew install mactop

mactop

Updating via Homebrew

brew update

brew upgrade mactop

Installation

To install mactop, follow these steps:

1. Ensure you have Go installed on your machine. If not, you can install it by following the instructions here: Go Installation Guide.

2. Clone the repository:

   git clone https://github.com/metaspartan/mactop.git
   cd mactop
   

3. Build the application:

   go build
   

4. Run the application:

   ./mactop
   

Usage

After installation, you can start mactop by simply running:

./mactop

Example with flags:

mactop --interval 1000 --foreground green

Custom Hex Colors:

# Use Dracula theme colors
mactop --foreground "#9580FF" --bg "#22212C"

Headless Mode (JSON Output):

# Run once and exit (great for scripts)
mactop --headless --count 1

# Run continuously with pretty printing
mactop --headless --pretty

# Run with different output formats (json, yaml, xml, toon)
mactop --headless --format toon

mactop Flags

• --headless: Run in headless mode (no TUI, output to stdout).
• --format: Output format for headless mode (json, yaml, xml, toon). Default is json.
• --count: Number of samples to collect in headless mode (0 = infinite).
• --pretty: Pretty print JSON output in headless mode.
• --interval or -i: Set the update interval in milliseconds. Default is 1000.
• --foreground: Set the UI foreground color. Accepts named colors (green, red, blue, etc.) or hex colors (#9580FF).
• --bg or --background: Set the UI background color. Accepts named colors (mocha-base, etc.) or hex colors (#22212C).
• --prometheus or -p: Set and enable the local Prometheus metrics server on the given port. Default is disabled. (e.g. -p 2112 to enable Prometheus metrics on port 2112)
• --unit-network: Network unit: auto, byte, kb, mb, gb (default: auto)
• --unit-disk: Disk unit: auto, byte, kb, mb, gb (default: auto)
• --unit-temp: Temperature unit: celsius, fahrenheit (default: celsius)
• --fan-control: Enable interactive fan speed control (⚠️ writes to SMC — use with caution, may require sudo on some macOS versions)
• --test or -t: Test IOReport power metrics (no sudo required)
• --menubar: Run as a macOS menu bar status item alongside the TUI.
• --version or -v: Print the version of mactop.
• --help or -h: Show a help message about these flags and how to run mactop.

Theme File Support

Create ~/.mactop/theme.json to customize colors:

Basic Colors

{
  "foreground": "#9580FF",
  "background": "#22212C"
}

Per-Component Colors (Optional)

Individual component colors that override the foreground:

• cpu: CPU gauge, CPU cores widget, CPU history chart
• gpu: GPU gauge, GPU sparkline, GPU history chart
• memory: Memory gauge, Memory history chart
• ane: ANE (Apple Neural Engine) gauge
• network: Network box, Network sparklines
• power: Power box, Power sparkline, Power history chart
• thunderbolt: Thunderbolt/RDMA box
• processList: Process list border and text color
• processListDim: Non-current-user (root/system) process text color (default: grey)
• processListSelected: Selected row foreground text color (default: auto contrast)
• systemInfo: System info box color

Example: Colorful Theme

{
  "foreground": "#B0BEC5",
  "background": "#212121",
  "cpu": "#FF5252",
  "gpu": "#448AFF",
  "memory": "#69F0AE",
  "ane": "#E040FB",
  "network": "#FFAB40",
  "power": "#FF6E40",
  "thunderbolt": "#E91E63",
  "processList": "#FFEB3B",
  "processListDim": "#555555",
  "processListSelected": "#FFFFFF",
  "systemInfo": "#00BCD4"
}

Example: Dracula PRO Palette

| Element | Hex | |------------|-----------| | Background | #22212C | | Foreground | #F8F8F2 | | Purple | #9580FF | | Cyan | #80FFEA | | Green | #8AFF80 | | Pink | #FF80BF | | Orange | #FFCA80 | | Red | #FF9580 |

Priority order: CLI flags > theme.json > saved config.

mactop Commands

Use the following keys to interact with the application while its running:

• q: Quit the application.
• r: Refresh the UI data manually.
• c: Cycle through the color themes.
• b: Cycle through the background colors.
• p: Party Mode (Randomly cycles through colors)
• i: Toggle Info layout (displays system info)
• F (Shift+f): Toggle Fan & Thermals layout (fan monitoring + all temperature sensors)
• l: Cycle through the 18 available layouts.
• + or =: Increase update interval (slower updates).
• -: Decrease update interval (faster updates).
• F9: Kill the currently selected process (pauses updates while selecting).
• Arrow Keys or h/j/k/l: Navigate the process list and select columns.
• g / G: Jump to the top or bottom of the process list.
• /: Search/Filter the process list by name (Esc to clear).
• Enter or Space: Sort by the selected column.
• h or ?: Toggle the help menu.

Fan Control Keys (requires --fan-control flag, only active in Fan layout)

• + or =: Increase fan speed (+100 RPM)
• -: Decrease