mactop

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) — AMC DCS byte counters on M1–M4, PMP AMCC rate histograms on M4 Pro/Max (no sudo), auto-calibrated power-based estimation on M5+ chips
• 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), plus headless one-shot commands (--fan-set, --fan-auto, --fan-status) for scripts, cron, and SSH
• 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
• Battery Monitoring: Battery percentage and charging state on MacBooks (auto-detected; shown in TUI, headless output, and Prometheus metrics)
• 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
• 22 Layouts: (l to cycle layouts) — includes a GPU + Memory focused layout with a DRAM read/write bandwidth history chart, a memory-pressure layout, plus a ports layout for listening TCP/UDP sockets
• Memory Pressure: kernel pressure state (Normal/Warning/Critical) via kern.memorystatus_vm_pressure_level, with approximate history for Activity Monitor-style green/yellow/red signal
  • New history_soc layout (a to jump to it): four large history StepCharts showing CPU, GPU, ANE, and DRAM + ANE Bandwidth (Read/Write) side-by-side, with a compact process list at the bottom. Ideal for observing sustained load, on-device Neural Engine inference, and memory bandwidth behavior over time.
• 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, battery (on MacBooks), 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)
• Multi-Language Support (i18n): 20 languages with automatic system language detection — English, Arabic, Chinese (Simplified & Traditional), Dutch, French, German, Hebrew, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish, Thai, Turkish, Vietnamese (--lang to override)

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 --lang ja

Built-in Themes:

# Dracula
mactop --foreground dracula --bg dracula-base

# Catppuccin
mactop --foreground mocha --bg mocha-base

Custom Hex Colors:

# Use Dracula PRO 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.), full palette themes (dracula, mocha, macchiato, frappe) or hex colors (#9580FF).
• --bg or --background: Set the UI background color. Accepts named colors (dracula-base, 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)
• --lang: Language override (e.g., en, es, ja, zh). Auto-detects system language if not set. Priority: CLI flag > MACTOP_LANG env var > config.json > system language.
• --fan-control: Enable interactive fan speed control (⚠️ writes to SMC — use with caution). Requires root: writing SMC fan keys is privileged, so you must run sudo mactop --fan-control. Without root every fan write is silently rejected (kIOReturnNotPrivileged) and the controls appear to do nothing.
• --fan-set <value>: Headless one-shot fan control (⚠️ writes to SMC, requires sudo): pin the fans to a target and exit. Accepts an absolute RPM (3000), a percent of each fan's min–max range (60%), min, max, or auto. See Headless Fan Control.
• --fan-id <n>: Apply --fan-set to a single fan ID instead of all fans.
• --fan-auto: Restore all fans to automatic control and exit (requires sudo).
• --fan-status: Print current fan state as JSON to stdout and exit (no root required).
• --menubar: Run as a macOS menu bar status item alongside the TUI.
• --overlay: Run as a floating overlay HUD window with FPS metrics. (Requires Screen Recording permission — see Permissions below)
• --dump-fps: Diagnostic tool that dumps display info, screen recording permission status, and tests CGDisplayStream at multiple output sizes. Useful for troubleshooting FPS display issues.
• --dump-temps: Diagnostic: dump all raw SMC temperature keys and exit.
• --dump-debug: Diagnostic: dump IOReport/HID/SMC/NVMe debug info and exit.
• --version or -v: Print the version of mactop.
• --help or -h: Show a help message about these flags and how to run mactop.

Permissions

mactop uses native Apple APIs and does not require sudo for core functionality (CPU, GPU, power, memory, temperatures, fans).

Screen Recording (required for FPS overlay)

The --overlay mode uses CGDisplayStream to track display frame rates (FPS and frame interval). On macOS 15 (Sequoia) and later, this requires Screen Recording permission for your terminal app:

1. Open System Settings → Privacy & Security → Screen Recording
2. Enable the toggle for your terminal app (Terminal.app, Ghostty, iTerm2, Warp, etc.)
3. Restart your terminal if prompted

Without this permission, the overlay will still work but FPS and frame interval metrics will show 0 / -.

Tip: Run mactop --dump-fps to verify screen recording access and test CGDisplayStream on your hardware. This is useful for troubleshooting if FPS metrics still aren't appearing.

Overlay Customization

The overlay HUD (--overlay) supports customization via ~/.mactop/config.json. You can control which metrics appear in collapsed mode, their order in expanded mode, and the overlay opacity.

Collapsed Mode Sections

Choose which metrics appear when the overlay is collapsed (default: FPS, Frame, CPU, GPU, Memory):

{
  "overlay": {
    "collapsed_sections": ["fps", "cpu", "gpu", "memory"]
  }
}

Expanded Mode Section Order

Reorder sections in expanded mode. Sections appear in the order listed:

{
  "overlay": {
    "expanded_order": [
      "fps", "frame", "cpu", "gpu", "memory",
      "power", "temps", "thermal", "fans",
      "bandwidth", "gpu_freq", "ane", "network"
    ]
  }
}

Available Sections

Section	Description
fps	Display FPS counter with sparkline
frame	Frame interval (ms) with sparkline
cpu	CPU usage bar with sparkline
gpu	GPU usage bar with sparkline
ane	ANE (Neural Engine) usage bar
memory	Memory usage bar
swap	Swap usage (only shown when swap is active)
power	Power breakdown (Package + CPU/GPU/ANE/DRAM)
bandwidth	DRAM bandwidth (GB/s)
gpu_freq	GPU frequency and TFLOPs
temps	CPU and GPU temperatures
thermal	Thermal state
fans	Fan RPM (only shown when fans present)
network	Network throughput

Persisted Opacity

{
  "overlay": {
    "opacity": 0.75
  }
}

Theme File Support

Create theme.json in mactop's config directory to customize colors:

• If XDG_CONFIG_HOME is set to an absolute path: $XDG_CONFIG_HOME/mactop/theme.json
• Otherwise: ~/.mactop/theme.json

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
• bandwidth: DRAM Bandwidth history chart (falls back to memory color)
• 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.

Config and Log Paths

mactop supports XDG directory variables while preserving the original path layout when those variables are unset.

File	XDG path when set	Legacy fallback
Config	$XDG_CONFIG_HOME/mactop/config.json	~/.mactop/config.json
Theme	$XDG_CONFIG_HOME/mactop/theme.json	~/.mactop/theme.json
Log	$XDG_STATE_HOME/mactop/mactop.log	~/.mactop/mactop.log

Relative XDG paths are ignored; XDG base directories must be absolute paths.

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 available layouts.
• o: Jump to the ports layout (listening TCP/UDP ports; press again to go back).
• m: Jump to the memory pressure layout (press again to go back).
• e: On the ports layout, toggle external-only filter.
• + 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 + sudo, only active in Fan layout)

Fan control writes to the SMC, which is privileged — run with sudo mactop --fan-control. Without root the keys below have no effect (mactop will show a warning in the Fan panel). Note: on recent macOS the system thermal governor may also override manual fan targets.

• + or =: Increase fan speed (+100 RPM)
• -: Decrease fan speed (-100 RPM)
• a: Toggle auto/manual fan mode
• 0: Set all fans to minimum speed
• 9: Set all fans to maximum speed
• R (Shift+r): Reset all fans to automatic control

Headless Fan Control

Fan control also works without the TUI — from scripts, cron jobs, or over SSH:

# Read fan state (no root needed) — JSON on stdout
mactop --fan-status

# Pin all fans to 3000 RPM (or a percent of each fan's min–max range, or min/max)
sudo mactop --fan-set 3000
sudo mactop --fan-set 60%
sudo mactop --fan-set max

# Pin only fan 1
sudo mactop --fan-set 2500 --fan-id 1

# Restore automatic fan control
sudo mactop --fan-auto        # (equivalent: sudo mactop --fan-set auto)

Each command performs its SMC writes, prints the resulting fan state as JSON to stdout (human-readable messages go to stderr; --pretty is honored), and exits — exit code 0 on success, 1 on failure. After writing, mactop reads the fan state back and fails with a warning if the OS silently rejected the write.

⚠️ Unlike the interactive TUI, --fan-set intentionally leaves the fans pinned in manual mode after mactop exits — that's what makes it usable headlessly. Nothing will restore automatic control until you run sudo mactop --fan-auto (or reboot). Pinning fans below their automatic speed under load can cause thermal throttling; the macOS thermal governor may also override manual targets on recent macOS versions.

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-22T18:16:57-07:00",
  "soc_metrics": {
    "cpu_power": 2.1959999999999997,
    "gpu_power": 5.38552801,
    "ane_power": 0,
    "dram_power": 5.702,
    "gpu_sram_power": 0.158,
    "system_power": 37.47166092432617,
    "total_power": 50.91318893432617,
    "gpu_freq_mhz": 643,
    "soc_temp": 62.562572,
    "cpu_temp": 62.562572,
    "gpu_temp": 58.38886
  },
  "memory": {
    "total": 137438953472,
    "used": 74062512128,
    "available": 63376441344,
    "swap_total": 5368709120,
    "swap_used": 4094689280
  },
  "net_disk": {
    "out_packets_per_sec": 589.4371024829012,
    "out_bytes_per_sec": 196028.18012655922,
    "in_packets_per_sec": 593.3256375185223,
    "in_bytes_per_sec": 74461.55739710879,
    "read_ops_per_sec": 0.32404458630175986,
    "write_ops_per_sec": 40.18152870141822,
    "read_kbytes_per_sec": 1.2961783452070395,
    "write_kbytes_per_sec": 308.4904461592754
  },
  "cpu_usage": 15.140564910346725,
  "gpu_usage": 53.51970510465884,
  "core_usages": [
    42.244224422442244,
    37.17105263157895,
    55.26315789473685,
    37.704918032786885,
    27.21311475409836,
    21.241830065359476,
    14.563106796116504,
    6.148867313915858,
    4.193548387096775,
    1.9417475728155338,
    30.718954248366014,
    20.846905537459286,
    1.9417475728155338,
    1.2944983818770228,
    0.3236245954692557,
    0,
    0,
    0,
    0,
    0
  ],
  "system_info": {
    "name": "Apple M1 Ultra",
    "core_count": 20,
    "e_core_count": 4,
    "p_core_count": 16,
    "gpu_core_count": 64
  },
  "thermal_state": "Normal",
  "thunderbolt_info": {
    "buses": [
      {
        "name": "TB4 Bus 5",
        "status": "Active (USB)",
        "icon": "⏺",
        "speed": "Up to 40 Gb/s",
        "domain_uuid": "9FDBA52F-DF7C-425E-B67B-FB80F9E1DCD6",
        "switch_uid": "0x05AC38BE5E390FE5",
        "receptacle_id": "6",
        "devices": [
          {
            "name": "ASM236X NVME",
            "mode": "USB",
            "info_string": "USB, SSD"
          }
        ],
        "network_stats": {
          "interface_name": "en7",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      },
      {
        "name": "TB4 Bus 4",
        "status": "Inactive",
        "icon": "○",
        "speed": "Up to 40 Gb/s",
        "domain_uuid": "5DD6DE43-051D-4B32-B044-23E57AA0EEC8",
        "switch_uid": "0x05AC38BE5E390FE4",
        "receptacle_id": "5",
        "network_stats": {
          "interface_name": "en6",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      },
      {
        "name": "TB4 @ TB3 Bus 3",
        "status": "Active",
        "icon": "ϟ",
        "speed": "20 Gb/s",
        "domain_uuid": "AF4CE493-9005-4E9D-8B8B-0198D27BABA3",
        "switch_uid": "0x05AC38BE5E390FE3",
        "receptacle_id": "4",
        "devices": [
          {
            "name": "Studio Display",
            "vendor": "Apple Inc.",
            "vendor_id": "0x0001",
            "mode": "TB3",
            "switch_uid": "0x0001AFBD0C588A00",
            "device_id": "0x801F",
            "info_string": "Apple Inc., TB3"
          }
        ],
        "network_stats": {
          "interface_name": "en5",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      },
      {
        "name": "TB4 Bus 2",
        "status": "Inactive",
        "icon": "○",
        "speed": "Up to 40 Gb/s",
        "domain_uuid": "D589EEFE-98CF-42EC-A729-6C3E523AA321",
        "switch_uid": "0x05AC38BE5E390FE2",
        "receptacle_id": "3",
        "network_stats": {
          "interface_name": "en4",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      },
      {
        "name": "TB4 Bus 1",
        "status": "Inactive",
        "icon": "○",
        "speed": "Up to 40 Gb/s",
        "domain_uuid": "6DAC6FCD-E102-4CCD-9D01-A75540E660CA",
        "switch_uid": "0x05AC38BE5E390FE1",
        "receptacle_id": "2",
        "network_stats": {
          "interface_name": "en3",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      },
      {
        "name": "TB4 Bus 0",
        "status": "Inactive",
        "icon": "○",
        "speed": "Up to 40 Gb/s",
        "domain_uuid": "63A80A32-E70C-4F22-84BE-EDE632A5BA3E",
        "switch_uid": "0x05AC38BE5E390FE0",
        "receptacle_id": "1",
        "network_stats": {
          "interface_name": "en2",
          "bytes_in": 0,
          "bytes_out": 0,
          "bytes_in_per_sec": 0,
          "bytes_out_per_sec": 0,
          "packets_in": 0,
          "packets_out": 0
        }
      }
    ]
  },
  "tb_net_total_bytes_in_per_sec": 0,
  "tb_net_total_bytes_out_per_sec": 0,
  "rdma_status": {
    "available": false,
    "status": "RDMA Disabled (use rdma_ctl enable in Recovery Mode)"
  },
  "cpu_temp": 62.562572,
  "gpu_temp": 58.38886
}
]

Confirmed tested working Apple Silicon 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
• A18 Pro
• M5
• M5 Pro
• M5 Max

(If you have a confirmed working Apple Silicon 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, System Power (PSTR, or the DC-in keys PDTR/PD0R on desktops where PSTR reads 0), fan speed monitoring (FNum, F*Ac/Mn/Mx/Tg/Md), fan speed control via SMCWrite, and comprehensive temperature sensor enumeration
• IOReport API: For CPU, GPU, ANE, and DRAM power consumption (no sudo required) — DRAM GB/s from AMC DCS byte counters (M1–M4) or PMP DCS BW / AMCC RD|WR|RD+WR histograms (M4 Pro/Max; AMC Stats does not subscribe on those chips). DRAM power is also used for auto-calibrated bandwidth estimation on M5+ chips
• 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-cores, P-cores, and S-cores on M5+) via CGO

License

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

Author and Contact

Carsen Klock - @carsenklock

Project Link: https://github.com/metaspartan/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

• gotui for the modern terminal UI framework.
• asitop for the original inspiration!
• htop for the process list and CPU cores inspiration!

Download History