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
• Detailed native metrics for CPU cores (E and P cores) via Apple's Mach Kernel API
• Memory usage and swap information
• Network usage information (upload/download speeds)
• Disk I/O activity (read/write speeds)
• Multiple volume display (shows Mac HD + mounted external volumes)
• Easy-to-read terminal UI
• 7 Layouts: Default, Alternative, Alternative Full, Vertical, Compact, Dashboard, and Gauges Only (L to cycle layouts)
• Persistent Settings: Remembers your Layout and Theme choice across restarts
• Customizable UI color (green, red, blue, cyan, magenta, yellow, and white) (C 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). List pauses while selecting.
• Headless Mode: Output JSON metrics to stdout for scripting/logging (--headless)
• Party Mode (Randomly cycles through colors) (P to toggle)
• Optional Prometheus Metrics server (default is disabled) (-p <port> or --prometheus <port>)
• 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/context-labs/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 --color green

mactop Flags

• --headless: Run in headless mode (no TUI, output JSON to stdout).
• --count: Number of samples to collect in headless mode (0 = infinite).
• --interval or -i: Set the update interval in milliseconds. Default is 1000.
• --color or -c: Set the UI color. Default is white. Options are 'green', 'red', 'blue', 'cyan', 'magenta', 'yellow', and 'white'. (-c green)
• --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)
• --test or -t: Test IOReport power metrics (no sudo required)
• --version or -v: Print the version of mactop.
• --help or -h: Show a help message about these flags and how to run mactop.

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.
• p: Party Mode (Randomly cycles through colors)
• l: Cycle through the 7 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.
• Enter or Space: Sort by the selected column.
• h or ?: Toggle the help menu.

Example Theme (Green) Screenshot (mactop -c green) on Advanced layout (Hit "l" key to toggle)

Example Headless Output (mactop --headless --count 1)

[
   {
      "timestamp":"2025-12-04T00:43:06-07:00",
      "soc_metrics":{
         "cpu_power":5.971,
         "gpu_power":1.43491417,
         "ane_power":0,
         "dram_power":4.119,
         "gpu_sram_power":0.04,
         "system_power":45.92987823486328,
         "total_power":11.564914169999998,
         "gpu_freq_mhz":645,
         "soc_temp":66.51124,
         "cpu_temp":66.51124,
         "gpu_temp":59.767166
      },
      "memory":{
         "total":137438953472,
         "used":95795822592,
         "available":41643130880,
         "swap_total":21474836480,
         "swap_used":20288831488
      },
      "net_disk":{
         "out_packets_per_sec":333.8985188256889,
         "out_bytes_per_sec":164.55632002792703,
         "in_packets_per_sec":295.37176665349403,
         "in_bytes_per_sec":39.33046303000927,
         "read_ops_per_sec":2.6754689008468664,
         "write_ops_per_sec":275.5732967872272,
         "read_kbytes_per_sec":43.83488247147506,
         "write_kbytes_per_sec":3763.2246601761335
      },
      "cpu_usage":24.052424536171074,
      "gpu_usage":13.709099344350134,
      "core_usages":[
         55.73770491803278,
         48.08743169398907,
         64.32432432432432,
         53.51351351351351,
         39.45945945945946,
         32.432432432432435,
         31.182795698924732,
         18.71657754010695,
         12.365591397849462,
         10.21505376344086,
         60,
         40.54054054054054,
         5.347593582887701,
         2.6737967914438503,
         2.1505376344086025,
         1.0810810810810811,
         1.06951871657754,
         1.0752688172043012,
         1.0752688172043012,
         0
      ],
      "system_info":{
         "name":"Apple M1 Ultra",
         "core_count":20,
         "e_core_count":4,
         "p_core_count":16,
         "gpu_core_count":64
      },
      "thermal_state":"Moderate",
      "cpu_temp":66.51124,
      "gpu_temp":59.767166
   }
]

Confirmed tested working M series chips

• M1
• M1 Pro
• M1 Max
• M1 Ultra
• M2
• M2 Pro
• M2 Max
• M2 Ultra
• M3
• M3 Pro
• M3 Max
• M3 Ultra
• M4
• M4 Pro
• M4 Max
• M5

(If you have a confirmed working M series chip that is not listed, please open an issue, so we may add it here!)

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork mactop
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

What does mactop use to get real-time data?

• Apple SMC: For SoC temperature sensors and System Power (PSTR)
• IOReport API: For CPU, GPU, ANE, and DRAM power consumption (no sudo required)
• IOKit: For GPU frequency table from pmgr device
• IOHIDEventSystemClient: Fallback for SoC temperature sensors
• NSProcessInfo.thermalState: For system thermal state (Nominal/Fair/Serious/Critical)
• Mach Kernel API (host_processor_info): For CPU metrics (E and P cores) via CGO
• gopsutil: For memory, swap, network, and disk I/O metrics
• ps: For process list information
• sysctl: For CPU model information
• system_profiler: For GPU Core Count

License

Distributed under the MIT License. See LICENSE for more information.

Author and Contact

Carsen Klock - @carsenklock

Project Link: https://github.com/context-labs/mactop

Disclaimer

This tool is not officially supported by Apple. It is provided as is, and may not work as expected. Use at your own risk.

Acknowledgements

• termui for the terminal UI framework.
• gopsutil for system memory, network, and disk monitoring.
• asitop for the original inspiration!
• htop for the process list and CPU cores inspiration!