Anmelden
tomcatzh

mac-system-stat

by @tomcatzh in Tools
0
0
# Install this skill:
npx skills add tomcatzh/mac-system-stat

Or install specific skill: npx add-skill https://github.com/tomcatzh/mac-system-stat

# Description

>

# SKILL.md

name: mac-system-stat
description: >
Generate a concise macOS host resource report focused on local-model readiness
and machine pressure. Use when the user asks about Mac resource usage, current
machine health, battery, CPU load, memory pressure, swap, disk headroom, GPU
model/capability, power draw, fan RPM, temperature sensors, or whether the
machine has enough headroom to run a local model. Triggers include "Mac status",
"system stats", "how's my machine", "memory pressure", "GPU utilization",
"power draw", "fan speed", "temperature", "can I run a local model".
macOS only, Apple Silicon first.

mac-system-stat

Produce a concise macOS host snapshot using small local helpers.

Quick Start

Run the aggregate report:

scripts/hoststat

For human-readable one-liner:

scripts/hoststat --text

Use the output directly when the user asks for a current system snapshot.

Available Helpers

Script What it reports
scripts/hoststat Aggregate JSON host snapshot (calls all others)
scripts/memstat RAM, compression, swap, memory pressure
scripts/cpustat CPU usage, load average, process counts, top CPU processes
scripts/gpustat GPU model, core count, live IOAccelerator utilization via Swift/IOKit
scripts/powerstat Apple Silicon IOReport-based power sampler (CPU/GPU/ANE/DRAM watts)
scripts/fanstat AppleSMC fan reader (count, RPM, min/max, mode)
scripts/tempstat AppleSMC temperature sensors + pmset thermal state
scripts/build-helpers Prebuild Swift helpers explicitly (optional; auto-built on first run)

Each helper outputs structured JSON. hoststat aggregates them all.

Interpretation Rules

Prioritize these signals for local-model readiness:

  1. Memory headroom β€” total, available-ish, compressed, swap used. High swap or compressed β†’ call it out.
  2. Current contention β€” CPU idle %, load average, top processes. If a few heavy processes dominate, name them.
  3. GPU β€” model and core count are reliable. Live utilization (device/renderer/tiler %) comes from IOAccelerator PerformanceStatistics.
  4. Power β€” CPU/GPU/ANE/DRAM watt draw from IOReport Energy Model. Values are short-window averages, not hardware-meter absolutes.
  5. Temperature β€” CPU, battery, ambient from AppleSMC. pmset -g therm for system thermal state.
  6. Fans β€” RPM from AppleSMC. 0 RPM on Apple Silicon can mean fans are currently stopped, not unreadable.

Output Style

Keep replies short and decision-oriented:

  • 1–2 sentence current state summary
  • 3–6 bullets for key numbers or bottlenecks
  • Clear conclusion: "ready now" / "usable but memory constrained" / "not ideal because X"

Build & Prerequisites

  • macOS only, Apple Silicon first
  • Python 3 (system Python is fine)
  • Xcode Command Line Tools (xcode-select --install) required for Swift-backed helpers (gpustat, powerstat, fanstat, tempstat)
  • Swift helpers auto-build into scripts/bin/ on first run; no manual build step needed
  • If swiftc is unavailable, Swift-backed helpers fail with structured JSON; memstat and cpustat still work

Design Notes

  • Default path avoids sudo
  • GPU reads IORegistry properties directly via IOKit, not ioreg text parsing
  • Power uses IOReport Energy Model deltas; non-privileged
  • Fan/temp use AppleSMC via IOKit; non-privileged
  • For deeper stats: sudo powermetrics --samplers tasks,cpu_power,gpu_power -n 1 (needs explicit user approval)
  • See references/metrics-notes.md for detailed metric interpretation guidance

# README.md

mac-system-stat

A concise macOS system report tool for AI agents. Produces structured JSON snapshots of CPU, memory, GPU, power, fans, and temperature β€” designed for OpenClaw skills and local-model readiness checks.

What it reports

Helper Metrics
hoststat Aggregate snapshot (calls all helpers below)
memstat RAM total/used/compressed/available, swap, memory pressure
cpustat CPU usage, load average, process counts, top processes
gpustat GPU model, core count, live utilization (device/renderer/tiler %)
powerstat CPU/GPU/ANE/DRAM power draw in watts (IOReport Energy Model)
fanstat Fan count, RPM, min/max, mode (AppleSMC)
tempstat Temperature sensors + thermal state (AppleSMC + pmset)

Requirements

  • macOS (Apple Silicon first, Intel partial support)
  • Python 3 (system Python works)
  • Xcode Command Line Tools for Swift-backed helpers (gpustat, powerstat, fanstat, tempstat)
xcode-select --install  # if not already installed

Quick start

# Full JSON report
./scripts/hoststat

# Human-readable one-liner
./scripts/hoststat --text

# Individual helpers
./scripts/memstat
./scripts/cpustat
./scripts/gpustat
./scripts/powerstat
./scripts/fanstat
./scripts/tempstat

Swift helpers auto-build on first run into scripts/bin/. To prebuild explicitly:

./scripts/build-helpers

Install as OpenClaw skill

Via ClawHub:

clawhub install mac-system-stat

Or manually:

cp -R . ~/.agents/skills/mac-system-stat

How it works

  • memstat/cpustat: Pure Python, uses vm_stat, sysctl, top, ps
  • gpustat: Python + Swift helper reading IOAccelerator via IOKit (non-privileged)
  • powerstat: Python + Swift helper sampling IOReport Energy Model channels (non-privileged)
  • fanstat/tempstat: Python + Swift helpers reading AppleSMC via IOKit (non-privileged)

All helpers run without sudo. For deeper stats: sudo powermetrics --samplers tasks,cpu_power,gpu_power -n 1

Example output

CPU 3.2% used, load 2.41/2.90/3.56 | Memory 42.1% used est (52.8GB/128.0GB),
pressure normal/low | Apple M4 Max/40c dev 0%, render 0% | Temp CPU 38.2C,
hottest 42.0C (Efficiency cluster) | Power CPU 7.29W, DRAM 1.35W |
Fans fan0 0rpm, fan1 0rpm | Top proc WindowServer pid 312 @ 5.2% CPU

License

MIT

# Related Skills

obra
executing-plans @obra

Use when you have a written implementation plan to execute in a separate session with review checkpoints

β˜… 32,766
obra
using-superpowers @obra

Use when starting any conversation - establishes how to find and use skills, requiring Skill...

β˜… 32,766

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚑ Amp πŸš€ Antigravity πŸ€– Claude Code πŸ¦€ Clawdbot πŸ“ Codex ▢️ Cursor πŸ€– Droid πŸ’Ž Gemini CLI πŸ™ GitHub Copilot πŸͺΏ Goose πŸ“Š Kilo Code πŸ”§ Kiro CLI πŸ’» OpenCode 🦘 Roo Code 🌲 Trae πŸ„ Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.