mxmon

https://github.com/yusufmo1/mxmon
Admin
Sudoless Apple Silicon telemetry CLI. Reads per-rail watts, CPU/GPU temperature, DVFS clocks, fan...
Tokens:4,933
Snippets:73
Trust Score:5.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Never run bare `mxmon` from a script or agent: it opens a full-screen TUI and blocks until the terminal closes. Always name a verb (snapshot, get, watch, top, check, health, explain, schema).
- mxmon needs no elevated privileges. Never prefix it with sudo, and never fall back to `sudo powermetrics` for power, temperature or frequency data. mxmon reads the same silicon sudoless.
- Run `mxmon schema --format compact` before querying. It prints every valid dot-path as `path:type` (about 7 KB) in exactly the dialect get, check and watch accept. Do not guess field names.
- Pass `--format json` (or ndjson, or compact) explicitly. The default `auto` prints a human summary whenever stdout is a terminal, and many agent harnesses allocate one.
- Exit 1 is a verdict, not a failure: `check` false, or `health` degraded. 2 is a usage error, 3 no data, 4 a refused control action, 5 an undecidable check. Only 2 and 3 mean the call was wrong.
- Keys are never omitted. A null domain means the source failed (see source_errors), is disabled (meta.features), or did not settle (meta.settled), never zero. Probe with `mxmon check 'thermal != null'`.
- Ratios are 0..1 and end in `_ratio`, never percentages. Per-process cpu_ratio is unclamped: 4.0 means four saturated cores. Watts end in `_w`, Celsius `_c`, whole MHz `_mhz`, bytes `_bytes`.
- Always bound `watch` with `--for <dur>` or `--count <n>`; unbounded it streams until the pipe closes. Bound a read verb's settle with `--timeout <dur>` when latency matters.
- Apple Silicon macOS only (M1 through M5). On Intel Macs, Linux or Windows mxmon has nothing to read; do not suggest it there.
- Install with `brew install yusufmo1/tap/mxmon` or `cargo install mxmon`. The crate, binary, Homebrew formula and GitHub repo are all named mxmon.

================
CODE SNIPPETS
================
### Verify Installation and Schema

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Check if mxmon is installed and display the available queryable paths in a compact format.

```sh
command -v mxmon || echo "install: brew install yusufmo1/tap/mxmon"
mxmon schema --format compact
```

--------------------------------

### Query Metrics via CLI

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Examples of common commands for retrieving system data or performing checks.

```sh
mxmon snapshot
mxmon get power.package_w thermal.throttling
mxmon watch power.package_w --for 10s
mxmon top cpu
mxmon check 'thermal.throttling == false' && cargo build
mxmon health
mxmon explain thermal
mxmon schema
mxmon kill 1234
```

--------------------------------

### Install mxmon from Prebuilt Binary

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Download and extract the latest prebuilt binary for Apple Silicon.

```sh
tar -xzf mxmon-aarch64-apple-darwin.tar.gz && ./mxmon
```

--------------------------------

### Install mxmon via Homebrew

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Use Homebrew to install the mxmon binary on Apple Silicon Macs.

```sh
brew install yusufmo1/tap/mxmon
```

--------------------------------

### Querying system metrics via CLI

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Examples of using mxmon to retrieve system metrics, check schemas, and gate processes based on thermal conditions.

```sh
mxmon schema --format compact                              # every queryable path and its type
mxmon get power.package_w thermal.throttling               # pull values, one per line
mxmon check 'thermal.throttling == false' && cargo build   # gate a build on a condition
mxmon top power                                            # rank processes by watts
```

--------------------------------

### Accessing system metrics via path syntax

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Examples of valid paths for querying system metrics, supporting array indexing with brackets or dot notation.

```text
power.package_w
power.ecpu.cores[0].power_w
processes.top[0].name
thermal.fans[0].rpm
```

--------------------------------

### Data Retrieval and Formatting

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Examples of retrieving system metrics using specific output formats and path filtering.

```sh
mxmon snapshot --format json
mxmon get power.package_w thermal.cpu_max_c            # bare values, one per line
mxmon snapshot --only power,thermal --format compact  # dotted.path=value lines
```

--------------------------------

### Bounding Streaming Output

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Examples of how to bound streaming commands to prevent infinite execution.

```bash
mxmon watch ... | head
```

--------------------------------

### Install mxmon via Cargo

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Install the mxmon crate directly using the Rust package manager.

```sh
cargo install mxmon
```

--------------------------------

### Build mxmon from Source

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Clone the repository and build the project using Cargo.

```sh
git clone https://github.com/yusufmo1/mxmon && cd mxmon
cargo build --release && ./target/release/mxmon
```

--------------------------------

### Discovering mxmon schema and help

Source: https://github.com/yusufmo1/mxmon/blob/main/AGENTS.md

Use these commands to explore available telemetry paths and command-line options.

```sh
mxmon schema --format compact    # every queryable path and its type, about 7 KB
mxmon --help                     # verbs, flags, examples, exit codes
```

--------------------------------

### Display Schema Information

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Print the queryable paths and their types in a compact format.

```sh
mxmon schema --format compact
```

--------------------------------

### Run mxmon with Privileges

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Execute with sudo to unlock CPU and memory columns for all system processes.

```sh
sudo mxmon
```

--------------------------------

### Execute process control commands

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Demonstrates using dry-run and forced execution modes for process termination.

```sh
mxmon kill 4310 --dry-run --format ndjson   # ok is null: nothing was attempted
mxmon kill 4310 --yes --format ndjson
```

--------------------------------

### Diagnostic Commands

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Commands for mapping user questions to specific system monitoring tasks.

```bash
mxmon explain slow
```

```bash
mxmon explain thermal
```

```bash
mxmon explain battery
```

```bash
mxmon top power
```

```bash
mxmon health --format json
```

```bash
mxmon get thermal.throttling thermal.cpu_max_c thermal.pressure
```

```bash
mxmon get power.package_w power.cpu_w power.gpu_w power.ane_w
```

```bash
mxmon get 'thermal.fans[0].rpm' 'thermal.fans[0].ratio'
```

```bash
mxmon top cpu --format json
```

```bash
mxmon top power --format json
```

```bash
mxmon get battery.health_ratio battery.cycle_count battery.charge_ratio
```

```bash
mxmon get storage.smart.unhealthy storage.smart.used_ratio storage.smart.power_on_hours
```

```bash
mxmon get soc.chip soc.pcpu_cores soc.ecpu_cores soc.gpu_cores
```

```bash
mxmon watch power.package_w thermal.cpu_max_c --for 60s --format ndjson
```

```bash
mxmon check 'thermal.throttling == false' && cargo build
```

--------------------------------

### Executing mxmon telemetry recipes

Source: https://github.com/yusufmo1/mxmon/blob/main/AGENTS.md

Common patterns for retrieving, monitoring, and diagnosing system telemetry data.

```sh
mxmon get power.package_w thermal.throttling   # pull specific values, one per line
mxmon snapshot                                 # the whole report (JSON when piped)
mxmon snapshot --only power,thermal            # just those groups
mxmon snapshot --format compact                # one greppable line per leaf
mxmon check 'thermal.throttling == false' && cargo build   # gate on a condition
mxmon watch cpu.self_ratio power.package_w --for 10s        # bounded NDJSON stream
mxmon top power                                # rank processes by a resource
mxmon health                                   # composite verdict, exit 1 if degraded
mxmon explain thermal                          # a plain-language diagnosis
```

--------------------------------

### Configure Key Bindings in config.toml

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Define custom key mappings for dashboard commands within the [keys] table of the configuration file.

```toml
[keys]
quit = ["ctrl+q", "f10"]
pause = ["space"]
view_thermal = ["3"]
```

--------------------------------

### Checking probe availability

Source: https://github.com/yusufmo1/mxmon/blob/main/skills/mxmon/SKILL.md

Use this command to verify if a sensor or metric source is available before performing comparisons, as comparing against null is undecidable.

```sh
mxmon check 'thermal != null'
```

--------------------------------

### Kill process with JSON output

Source: https://github.com/yusufmo1/mxmon/blob/main/AGENTS.md

Executes a kill command on a process and returns the result in ndjson format.

```sh
$ mxmon kill 4310 --yes --format ndjson
[{"action":"signal","error":null,"name":"node","ok":true,"pid":4310,"signal":"SIGTERM"}]
```

--------------------------------

### Clear Gatekeeper Quarantine

Source: https://github.com/yusufmo1/mxmon/blob/main/README.md

Remove the quarantine attribute from the binary if it fails to launch on macOS.

```sh
xattr -d com.apple.quarantine ./mxmon
```
Tokens:
Raw