Mole Status Command System Metrics: Complete Guide to Host Monitoring

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. 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, metrics_memory.go, and 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) 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.

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 gathers processor statistics via system calls or performance counters.
• collector_memory.go reads virtual memory statistics and macOS pressure levels.
• 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

mole status

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

Export Metrics as JSON

mole status --json | jq .

Parse JSON in 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.
• 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.

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, collector_memory.go, and 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.

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, which organizes metrics into cards and sparklines based on the collected snapshot data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}