mactop for Apple Silicon: Terminal Monitoring and Metrics

What mactop measures on Apple Silicon Macs

mactop solves the problem of inspecting an Apple Silicon Mac without moving to a graphical system monitor. It is intended for developers, power users, and terminal-focused administrators who need CPU, GPU, neural-engine, memory, and power information during a workload. Its architecture is explicitly limited to ARM64 Macs running macOS Monterey 12.3 or later.

The dashboard covers more than overall CPU utilization. The README lists CPU and GPU percentages, E-Core and P-Core information, S-Cores on M5 systems, GPU frequency, ANE usage, DRAM bandwidth, system power, temperatures, and thermal state. It also covers memory and swap, network throughput, disk activity, Thunderbolt bandwidth, connected Thunderbolt and USB4 devices, fan RPM, and battery status on MacBook models.

Process information is part of the interface as well. The README describes a process list similar in format to htop, name filtering, keyboard navigation, freezing, and process termination with confirmation. Proportional per-process GPU usage is labeled experimental, so it should be evaluated separately from the system-wide metrics.

This scope makes mactop useful for two different jobs. An interactive user can inspect changing load through the terminal UI. A scripting user can request headless output or start the optional Prometheus server. That second use matters because a terminal dashboard alone is a poor integration point for longer-term collection.

How mactop accesses Apple hardware metrics

The README says mactop reads native interfaces including SMC, IOReport, IOKit, and IOHIDEventSystemClient without requiring sudo for its monitoring functions. It is implemented in Go and CGO, allowing a Go terminal application to interact with macOS-specific APIs. The repository contains internal packages, `main.go`, and native supporting code, although the README does not document the complete internal call path.

The visible behavior is based on repeated metric collection and redisplay. The default update interval is 1000 milliseconds, and keyboard controls can make updates faster or slower. Depending on the selected layout, the screen combines current values, gauges, process information, and short histories. Layout and theme choices persist across restarts.

Metric collection methods differ across chip families. The README states that DRAM bandwidth uses AMC DCS byte counters on M1 through M4 and PMP AMCC rate histograms on M4 Pro and M4 Max. On M5 and later chips, mactop uses auto-calibrated, power-based estimation. This difference matters when comparing readings across machines: similar values in the interface do not necessarily represent identical measurement methods.

Fan control is a separate write path. Normal fan metrics are displayed alongside RPM, target speed, mode, and visual bars. Optional controls can write to SMC, so monitoring and actuation should not be treated as having the same system impact.

Installing and launching mactop

The README offers installation through Homebrew and installation from source. Homebrew is the shorter route for users who already manage Mac command-line software through it:

brew install mactop

After installation, the documented launch command is:

mactop

On a compatible Mac, mactop should open its terminal dashboard. The README does not document an uninstall command, configuration reset command, or rollback procedure for the Homebrew installation.

The source route requires Go. The module declares `go 1.25.4`, so the source build depends on that Go toolchain requirement. The documented clone sequence is:

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

After entering the repository, build and launch the executable with:

go build

./mactop

The repository's `Makefile` also defines `make build`, `make run`, `make test`, and `make clean`. Its `test` target runs tests under `./internal/app/...` and `./internal/i18n/...`. That command does not cover every package in the repository, so it should not be described as a complete repository-wide test.

Starting with headless and Prometheus output

The first useful scripted operation is headless collection. According to the README, `--headless` writes JSON metrics to standard output. `--pretty` formats that JSON for readability, while `--count <n>` sets the collection count. The format can also be changed with `--format <format>`, and the documented choices are JSON, YAML, XML, CSV, and TOON. JSON is the default headless format.

For example, the README documents a themed Japanese interface with a one-second interval:

mactop --interval 1000 --foreground green --lang ja

This launches the interactive interface. The README does not state whether headless mode exits after one sample or continues emitting metrics. The interaction between `--headless` and `--count` therefore needs checking in the local command output before it is placed into an unattended job.

Prometheus support is disabled by default. It can be enabled with either `-p <port>` or `--prometheus <port>`. The README says the exported data includes CPU, GPU, ANE, per-core usage, power components, DRAM bandwidth, memory, network, disk, fan metrics, temperatures, thermal state, and battery metrics where applicable. It does not give the scrape endpoint, authentication configuration, or retention behavior, so those details cannot be assumed.

Controlling layouts, fans, and processes

mactop provides 22 layouts according to the README. The `l` key cycles between them. One layout concentrates on GPU, memory, and DRAM bandwidth history. Another presents kernel memory pressure as a Normal, Warning, or Critical state. A ports view shows listening TCP and UDP sockets. The `history_soc` layout, reached with `a`, contains history charts for CPU, GPU, ANE, and DRAM bandwidth activity.

The TUI also supports foreground and background color changes with `c` and `b`. Layout and theme choices are remembered across restarts. Update frequency is controlled with `-` and `=` rather than only through a command-line setting. These controls make the display adaptable to different terminals, but they also increase the amount of behavior that differs between the default view and a selected layout.

Fan monitoring displays RPM, target speed, Auto or Manual mode, and RPM bars. The optional `--fan-control` flag permits interactive changes that write to SMC. Headless commands include `--fan-set`, `--fan-auto`, and `--fan-status`, which the README positions for scripts, cron, and SSH. Because these commands alter fan state rather than merely reading it, their exact arguments and supported models should be verified before use.

For process handling, F9 opens a kill action protected by confirmation. `/` filters the process list, `j` and `k` scroll, `g` moves to the top, and `G` moves to the bottom. Freezing with `f` pauses process-list updates, which can help when values change too quickly to read.

Platform limits, licensing, and upgrade cost

The Apple Silicon and macOS Monterey 12.3 restrictions are hard boundaries. mactop is not an option for an Intel Mac, and the README does not publish a model-by-model compatibility table. It advertises support for all Apple Silicon models, but several features are narrower. DRAM counters, histograms, or estimation vary by chip generation. S-Core details apply to M5, RDMA depends on Thunderbolt 5 availability, battery information applies to MacBooks, and fan availability depends on the machine's sensors and controls.

The project is not archived, and its last push was on 2026-09-30. Releases include v2.1.6 on 2026-09-30, v2.1.5 on 2026-06-14, and v2.1.4 on 2026-06-09. The README documents updating a Homebrew installation:

brew update

brew upgrade mactop

It does not document rollback to a previous Homebrew version or migration steps between mactop releases. Source users must also consider that `go.mod` names Go 1.25.4 and several moving dependencies, including versioned Go libraries for terminal UI, i18n, Prometheus, YAML, and TOON.

The repository identifies the MIT license. The exact `LICENSE` file governs permissions and conditions. The README does not provide a support policy, security response process, or long-term compatibility promise for future macOS releases, so adoption should account for those undocumented operational limits.

Editorial conclusion

mactop is suitable for Apple Silicon Mac users who want an interactive terminal dashboard, formatted metric exports, or a local Prometheus endpoint. It is not suitable for Intel Macs or users requiring documented rollback procedures. Verify model-specific metric availability first, particularly for DRAM bandwidth, fan control, RDMA, per-process GPU usage, and M5 S-Core data.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. metaspartan/mactop on GitHub
4. README
5. Releases