Mac AI Doctor — Will this model fit your Mac?

The readout

Four verdicts. No spreadsheets to interpret.

Every check ends in one word. Confidence describes how complete the model's metadata is — not how accurate a benchmark would be. Because this is screening, not a benchmark.

≤ 80%

COMFORTABLE

High estimate uses at most 80% of available memory. Good fit — keep normal apps modest for best stability.

< 20% headroom

TIGHT

Estimated to fit with less than 20% headroom. Close memory-heavy apps or reduce context / concurrency.

> available

UNLIKELY

High estimate exceeds available memory. Choose a smaller or more-quantized model, or reduce context.

no metadata

UNKNOWN

Weight-size metadata is unavailable. Provide a repo exposing safetensors sizes, or a local GGUF file.

Capabilities

Deliberately narrow. Ruthlessly honest.

One job: inspect one exact model for one Apple Silicon memory budget, before a large download. No model rankings, no throughput claims, no telemetry.

Any public HF repository

Point it at a Hugging Face model ID or URL. It reads only config.json, the safetensors index, and the API's file-size listing.

Local GGUF & MLX

Pass a local .gguf file — it reads the 24-byte header and file size — or an MLX / local config directory.

Transparent memory range

Weights, KV cache and runtime are shown as an honest low–high range, with the exact assumptions that produced it.

Your workload, dialed in

Tune --context, --concurrency, and --kv-dtype to model exactly how you plan to run inference.

Compare & recommend

Put two models side by side under the same workload, or ask for a conservative starting class for coding, chat, or vision.

Shareable output

Machine-readable --json, plus a browser UI that exports a Markdown report or an SVG compatibility badge.

The formula

No black box.

Decimal GB. Unified memory is shared with macOS, apps and the GPU — the range reflects that.

weights = stored_weight_bytes * 1.06

KV = 2 * layers * KV_heads * head_dim

* context * concurrency * dtype_bytes

runtime = max(1GB, weights * 12%)

+ 0.25GB * concurrency

range = subtotal * 1.10 .. subtotal * 1.25

Bounded reads

Weight contents are never downloaded.

✓Reads config.json to learn the model's shape.
✓Reads the safetensors index for stored weight sizes.
✓Reads the Hugging Face file-size listing — bytes on disk, not the bytes themselves.
✓Reads the 24-byte header of a local GGUF, plus its file size.

No weights. No credentials collected. Gated repositories may use your existing Hugging Face authentication — nothing more.

Positioning

What makes it different?

If you need broad cross-platform recommendations or community benchmarks, other tools fit better. Mac AI Doctor is built for transparent, exact-repository screening on Macs.

Capability	Mac AI Doctor	Static calculators	Hardware recommenders
Inspect an arbitrary public HF repository	YES	usually no	varies
Accept local MLX / config dirs & GGUF files	YES	NO	varies
Download no model weights during a check	YES	yes	varies
Show context, concurrency & KV-cache assumptions	YES	varies	varies
Produce a transparent memory range	YES	varies	varies
Rank hundreds of models or predict tokens/sec	NO	sometimes	often

Get started

In under a minute.

Run once without installing, install the CLI, or launch the browser UI locally.

$uvx mac-ai-doctor check https://huggingface.co/mlx-community/Qwen3-8B-4bit

Inputs: a Hugging Face model ID or URL · a local .gguf file · a local / MLX directory with config.json.