Getting Started¶

Get fm running on your Mac in under a minute.

Requirements¶

Requirement	Notes
macOS on Apple Silicon	Tested on an M4 MacBook Pro; the fanless layout is simulated with `FANMON_FANLESS=1`. Intel Macs are untested.
Python 3.11+	`python3 --version`. The app uses modern syntax (`X \| None`).
Stats.app (optional)	A free menu-bar system monitor. `fm` reuses its read-only SMC helper to read fan RPM and temperatures — no extra drivers or `sudo`. Without it the FAN and TEMP tiles are blank; CPU, memory, throttle, processes and the verdict all work.

MacBook Air owners

You have no fan, and fm knows: the FAN tile becomes COOLING and shows how much macOS is throttling the CPU. Head straight for the CPU and Memory tabs (] twice) — that's where an Air's heat shows up.

??? info "Why Stats.app?" Reading Apple-Silicon fan RPM and temperatures needs the SMC, which has no supported public API. Rather than bundle a signed driver, fm shells out to the SMC reader that ships with Stats:

```
/Applications/Stats.app/Contents/Resources/smc
```

This is the exact same helper the [watchdog](watchdog.md) uses, so no new
privileged code enters the system. If you'd rather not install Stats, see
[Troubleshooting](troubleshooting.md).

Install¶

Fresh cloneAlready have the source

git clone https://github.com/jensenloke/macos-fanMonitor
cd macOS-fanMonitor
./install.sh

cd ~/Documents/tools/macOS-fanMonitor   # wherever you keep it
./install.sh

install.sh does three things:

Creates a private virtualenv at .venv/ inside the project.
Installs rich and textual into it.
Symlinks the fm launcher into ~/.local/bin/.

First run¶

fm

The full-screen ABC mark assembles first while initial hardware sampling runs in the background. It remains visible for at least three seconds, then opens the live dashboard with its Fan Monitor - Agentic Builders Collective header and Verdict banner. Press q to quit. Use fm --no-anim or FANMON_NO_ANIM=1 to skip the boot screen.

??? tip "Command not found?" If fm isn't found, ~/.local/bin isn't on your PATH. Add it to your ~/.zshrc:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Then open a new shell. The launcher follows its own symlink, so it works
from any directory once it's on `PATH`.

One-shot mode¶

For scripts, cron, or a quick non-interactive look, print a single frame and exit:

fm --once

That renders the same information once and exits — handy for logging the state at the moment a fan event fires.

Verify your install¶

Two quick checks:

fm --once | head        # dashboard renders, fan/temp/swap lines present
./.venv/bin/python smoke_test.py   # headless TUI test → "SMOKE OK"

Updates¶

fm keeps itself current: a background check against PyPI (≤ every 12h) and, if a newer release is known, a self-upgrade on the next launch. Manual control: fm update, fm update --check, fm update --off; FANMON_NO_UPDATE=1 disables it entirely.

Optional: AI harness¶

fm works fully without it. If you want an LLM second opinion (an "AI" tab, a to consult, threshold triggers), set it up from the shell:

fm ai providers      # see what's reachable
fm ai setup --from-omp dgx        # or --base-url … --model … --key-source …
fm ai test --tools   # verify chat + tool calling

Details, privacy notes, and examples for Ollama / LM Studio / OpenAI: AI harness.

You're set. Next up: User Guide.