# Mole Status Command System Metrics: Complete Guide to Host Monitoring

> Discover Mole's status command system metrics. Monitor CPU GPU memory disk I/O network throughput battery health hardware specs & more via interactive UI or JSON output. Get comprehensive host monitoring.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: deep-dive
- Published: 2026-03-20

---

**Mole's `status` command aggregates 15+ categories of system metrics—including CPU, GPU, memory, disk I/O, network throughput, battery health, and hardware specifications—delivering them through an interactive terminal UI or JSON output for automation.**

The `status` command in tw93/Mole is a comprehensive system monitoring tool that exposes deep hardware and OS-level telemetry. Built in Go, it collects real-time performance data through platform-specific collectors and structures it into a unified `MetricsSnapshot`. Whether you need a quick visual health check or structured data for scripts, the Mole status command system metrics provide the visibility required for effective host monitoring.

## Architecture of the MetricsSnapshot

All metrics are centralized in the **`MetricsSnapshot`** struct defined in [`cmd/status/metrics.go`](https://github.com/tw93/Mole/blob/main/cmd/status/metrics.go). This structure acts as a single source of truth, populated by platform-specific collector implementations found in `cmd/status/collector_*.go` files (such as [`metrics_cpu.go`](https://github.com/tw93/Mole/blob/main/metrics_cpu.go), [`metrics_memory.go`](https://github.com/tw93/Mole/blob/main/metrics_memory.go), and [`metrics_disk.go`](https://github.com/tw93/Mole/blob/main/metrics_disk.go)).

The snapshot captures instantaneous system state with nanosecond precision timestamps, enabling both real-time visualization and historical trend analysis when exported.

## Comprehensive Metric Categories

The Mole status command system metrics span hardware inventory, resource utilization, and peripheral status. Each category maps to a specific struct within the snapshot.

### Host and Hardware Information

Basic host identification and static hardware specifications are captured in two dedicated structures:

- **`Host`**, **`Platform`**, **`Uptime`**, and **`Procs`** fields (lines 60‑65 in [`cmd/status/metrics.go`](https://github.com/tw93/Mole/blob/main/cmd/status/metrics.go)) provide the hostname, OS platform, system uptime, and running process count.
- **`HardwareInfo`** (lines 84‑90) contains the machine model, CPU model identifier, total RAM, internal disk size, macOS version, and display refresh rate.

### CPU and GPU Telemetry

Processor and graphics metrics offer granular insight into compute performance:

- **`CPUStatus`** (lines 104‑115) reports overall usage percentage, per-core utilization (or estimated values when hardware counters are restricted), 1‑5‑15 minute load averages, and core topology including physical, logical, performance (P), and efficiency (E) core counts for Apple Silicon.
- **`GPUStatus`** (lines 117‑124) provides a slice of available GPUs with device name, utilization percentage, memory usage versus total, core count, and optional status notes.

### Memory and Storage Analysis

RAM and disk utilization metrics help diagnose resource pressure:

- **`MemoryStatus`** (lines 126‑134) tracks used and total bytes, usage percentage, swap consumption, cached bytes, and the macOS memory pressure level.
- **`DiskStatus`** (lines 136‑144) enumerates mounted volumes with mount point, device identifier, used/total capacity, filesystem type, and external drive flags.
- **`DiskIOStatus`** (lines 93‑96) captures real-time read and write throughput in MB/s.

### Network and Connectivity

Network performance and configuration are monitored through:

- **`NetworkStatus`** (lines 146‑151) lists per-interface statistics including interface name, Rx/Tx rates in MB/s, and the primary IP address.
- **`NetworkHistory`** (lines 153‑156) maintains rolling buffers of recent network rates to render sparkline graphs in the TUI.
- **`ProxyStatus`** (lines 161‑165) indicates whether a system proxy is enabled, its type, and host address.

### Power, Thermal, and Battery

Mobile and desktop power management metrics include:

- **`BatteryStatus`** (lines 167‑174) reports charge percentage, charging status, time remaining, battery health, cycle count, and design capacity.
- **`ThermalStatus`** (lines 176‑184) provides thermal power numbers and pressure states to indicate thermal throttling conditions.

### Processes, Sensors, and Peripherals

Additional system state captured includes:

- **`ProcessInfo`** (lines 98‑102) lists top processes by CPU and memory consumption with process names and utilization percentages.
- **`SensorReading`** (lines 186‑191) captures generic hardware sensor data with labels, values, units, and optional notes.
- **`BluetoothDevice`** (lines 193‑197) tracks connected Bluetooth peripherals with device names, connection states, and battery levels.

## Output Modes: Interactive UI vs JSON

The Mole status command system metrics can be consumed in two formats controlled by command-line flags.

**Interactive Terminal UI** (default) renders the `MetricsSnapshot` as animated cards, sparklines, and the mascot character. The view logic resides in [`cmd/status/view.go`](https://github.com/tw93/Mole/blob/main/cmd/status/view.go).

**JSON Output** (`--json`) serializes the raw snapshot for programmatic processing, logging, or external monitoring integrations.

## Implementation and Collection Strategy

Data gathering is implemented through platform-specific collectors in `cmd/status/collector_*.go` files. Each collector targets a specific metric group:

- [`collector_cpu.go`](https://github.com/tw93/Mole/blob/main/collector_cpu.go) gathers processor statistics via system calls or performance counters.
- [`collector_memory.go`](https://github.com/tw93/Mole/blob/main/collector_memory.go) reads virtual memory statistics and macOS pressure levels.
- [`collector_disk.go`](https://github.com/tw93/Mole/blob/main/collector_disk.go) inspects mount points and I/O statistics.

The `Collector` interface aggregates these into a single `MetricsSnapshot` instance that is passed to the rendering layer or JSON encoder.

## Usage Examples

### Run the Interactive Status Dashboard

```bash
mole status

```

Press `k` to toggle the mascot animation. Press `q`, `Esc`, or `Ctrl-C` to exit.

### Export Metrics as JSON

```bash
mole status --json | jq .

```

### Parse JSON in Go

```go
package main

import (
    "encoding/json"
    "fmt"
    "os/exec"
)

func main() {
    out, err := exec.Command("mole", "status", "--json").Output()
    if err != nil {
        panic(err)
    }
    
    var snapshot map[string]interface{}
    if err := json.Unmarshal(out, &snapshot); err != nil {
        panic(err)
    }
    
    fmt.Printf("Host: %s\n", snapshot["host"])
    fmt.Printf("Health Score: %.0f\n", snapshot["health_score"])
}

```

## Summary

- **Mole status command system metrics** are defined in the `MetricsSnapshot` struct within [`cmd/status/metrics.go`](https://github.com/tw93/Mole/blob/main/cmd/status/metrics.go).
- The tool captures 15+ metric categories spanning CPU, GPU, memory, disk I/O, network, battery, thermal sensors, and Bluetooth devices.
- Data collection is implemented via platform-specific collectors in `cmd/status/collector_*.go` files.
- Output formats include an interactive TUI (`mole status`) and machine-readable JSON (`mole status --json`).

## Frequently Asked Questions

### What system metrics does Mole's status command provide?

Mole's status command provides comprehensive system metrics including host information (hostname, uptime, platform), hardware details (CPU model, RAM, disk size), real-time performance data (CPU usage per core, GPU utilization, memory pressure, disk I/O rates), network statistics (Rx/Tx rates per interface), power metrics (battery health, thermal status), and connected peripherals (Bluetooth devices). These are structured in the `MetricsSnapshot` struct in [`cmd/status/metrics.go`](https://github.com/tw93/Mole/blob/main/cmd/status/metrics.go).

### How do I export Mole status metrics to JSON for monitoring scripts?

Use the `--json` flag when invoking the status command: `mole status --json`. This serializes the entire `MetricsSnapshot` to standard output as JSON, bypassing the interactive TUI. You can pipe this output to tools like `jq` for filtering or ingest it directly into monitoring systems and log aggregators.

### Where does Mole collect its system metrics from?

Mole collects metrics through platform-specific implementations located in `cmd/status/collector_*.go` files (such as [`collector_cpu.go`](https://github.com/tw93/Mole/blob/main/collector_cpu.go), [`collector_memory.go`](https://github.com/tw93/Mole/blob/main/collector_memory.go), and [`collector_disk.go`](https://github.com/tw93/Mole/blob/main/collector_disk.go)). These collectors interface with operating system APIs, hardware performance counters, and system frameworks to populate the `MetricsSnapshot` structure defined in [`cmd/status/metrics.go`](https://github.com/tw93/Mole/blob/main/cmd/status/metrics.go).

### Can I customize the Mole status display or disable the mascot?

Yes. When running `mole status` in interactive mode, press `k` to toggle the animated mascot on or off. This preference is persisted in `~/.config/mole/status_prefs`. The TUI itself is rendered by [`cmd/status/view.go`](https://github.com/tw93/Mole/blob/main/cmd/status/view.go), which organizes metrics into cards and sparklines based on the collected snapshot data.