GitHub repo · Gist mirror · run it instantly: npx sysscope
A small, modular, read-only shell tool that audits any Mac (and most Linux boxes) and tells you, in plain language:
- What hardware you have — CPU, GPU, Neural Engine, RAM, storage, battery, thermals
- What dev & AI software is installed — languages, package managers, containers, VMs, LLM tooling
- Which local AI models you can actually run — a model-by-model "fits / tight / too big" verdict tuned to your memory
- What to run together — a health scorecard and concurrency advice so you don't blow your RAM budget
It prints a colorized terminal report and writes a shareable Markdown report (plus optional JSON). It never changes your system — it only reads.
Made for the common question: "I want to run Ollama / Docker / emulators / VMs on this machine — what will actually run well, and what should I pick?"
▶ Try it now (no install):
npx sysscope- 🧠 AI capability engine — computes a realistic memory budget (unified RAM on Apple Silicon, VRAM on NVIDIA, or CPU-only) and grades 15 popular Ollama models against it.
- 🖥️ Real hardware detection — Apple Silicon core layout, GPU cores, Metal version, NVIDIA VRAM, disk pressure, battery health, thermal throttling.
- 🩺 Health scorecard — disk / memory / AI / battery rated 🟢🟡🟥 with one-line reasons.
- 🧩 Modular — one job per file (
lib_*,mod_*). Easy to read, extend, or trim. - 📦 Single-file bundle —
build.shconcatenates everything intoaudit-bundle.shforcurl | bashdistribution. - 🔒 Privacy mode —
--shareredacts serials, UUIDs, and hostname so you can post the report publicly. - 🤝 Interactive or unattended — menu-driven by default, fully scriptable with flags.
- 📄 Multiple outputs — pretty terminal, Markdown report, and machine-readable JSON.
- 🐚 Portable — pure Bash, compatible with the bash 3.2 that ships on macOS (no extra installs).
npx sysscopeThat's the whole thing. npx fetches and runs it; you get an interactive menu, then a saved sysscope-report-*.md. Pass any flag straight through:
npx sysscope --ai-only # "which models can I run?"
npx sysscope --quick --yes # fast, unattended
npx sysscope --share # redacted, shareable reportNeeds Node (for
npx) andbash(built in on macOS/Linux; use WSL/Git Bash on Windows). The launcher only runs the local audit — it makes no network calls.Want the very latest (unreleased) version straight from
main? Usenpx github:aoneahsan/sysscope.
git clone https://github.com/aoneahsan/sysscope.git
cd sysscope
chmod +x audit.sh
./audit.sh# Download just the self-contained bundle and run it
curl -fsSLO https://raw.githubusercontent.com/aoneahsan/sysscope/main/audit-bundle.sh
bash audit-bundle.sh
# …or pipe it (always review remote scripts first!):
curl -fsSL https://raw.githubusercontent.com/aoneahsan/sysscope/main/audit-bundle.sh | bash./audit.sh [options]
PRESETS
-f, --full Full audit (default)
-q, --quick Faster: skips software inventory & deep disk scan
-a, --ai-only Just "what AI models can I run?"
OUTPUT
-o, --output FILE Markdown report path (default: ./sysscope-report-<timestamp>.md)
--no-report Terminal only
--json [FILE] Also write JSON metrics
--deep Include slow probes (largest items in home folder)
PRIVACY
--share Redact serials / UUIDs / hostname (safe to publish)
BEHAVIOR
-y, --yes Non-interactive (accept defaults)
--no-color Disable colors
--gist-url URL Feedback URL printed in the report
-V, --version Print version
-h, --help Show help
./audit.sh # interactive, full audit, saves a report
./audit.sh --quick --yes # fast, unattended
./audit.sh --ai-only # which models fit?
./audit.sh --share -o report.md # redacted, shareable
./audit.sh --json metrics.json # full audit + JSON metrics== Local AI / LLM Capability ==
Inference backend unified memory (Metal GPU shares 16 GB)
Usable memory budget ~11.5 GB for the model + context
Capability tier Comfortable — 7–9B daily (14B tight)
[OK ] Hardware-accelerated local inference is available.
Which models fit (Ollama, Q4 quantization)
MODEL PARAMS ~SIZE FITS?
llama3.1:8b 8B 4.7GB ✅ yes
qwen2.5-coder:7b 7B 4.7GB ✅ yes
gemma2:9b 9B 5.4GB ✅ yes
qwen2.5:14b 14B 9.0GB 🟡 tight
gemma2:27b 27B 16.0GB 🔴 too big
== Health Scorecard & Recommendations ==
Disk 🟥 critical Only 19 GB free — reclaim before installing tools.
Memory 🟢 good 16 GB — one very-heavy workload at a time.
Local AI 🔭 Comfortable — 7–9B daily (14B tight) (~11.5 GB budget)
The Markdown report contains the same content as GFM tables, ready to paste into an issue, wiki, or gist comment.
- Find the memory budget that matters for inference:
- NVIDIA GPU → ~92% of VRAM (
nvidia-smi). - Apple Silicon →
total RAM − 4.5 GB(the GPU shares unified memory; the rest is for macOS + a couple of apps). - CPU-only →
total RAM − 3 GB, with a "this will be slow" warning.
- NVIDIA GPU → ~92% of VRAM (
- Grade each model in a built-in catalog: a model comfortably fits if
size × 1.3 ≤ budget(the ×1.3 covers the KV cache / context), is tight if it merely fits, else too big. - Pick a tier (Minimal → Workstation) and print a tailored starter set plus install commands.
Generation speed is memory-bandwidth-bound, so the tool gives qualitative tok/s ranges rather than false precision.
Note: on Apple Silicon, local LLM runtimes (Ollama, llama.cpp) use the GPU via Metal, not the Neural Engine. SysScope says so explicitly to clear up a common myth.
Each file does one thing and is sourced by audit.sh:
| File | Responsibility |
|---|---|
audit.sh |
Entry point: arg parsing, interactive menu, orchestration |
lib_core.sh |
Output/formatting, OS detection, prompts, helpers |
lib_report.sh |
Markdown + JSON document lifecycle, tables |
mod_system.sh |
OS, model, chip, kernel identity |
mod_cpu.sh |
CPU topology (P/E cores) |
mod_memory.sh |
RAM, swap, pressure |
mod_gpu.sh |
GPU, unified vs discrete VRAM, accelerators |
mod_storage.sh |
Disk capacity, free space, biggest items |
mod_power.sh |
Battery health, charge, thermal throttling |
mod_software.sh |
Languages, package managers, containers, AI tooling |
mod_ai.sh |
Local-AI capability assessment |
mod_recommend.sh |
Health scorecard + workload guidance |
build.sh |
Bundles all of the above into audit-bundle.sh |
Add a mod_yours.sh that defines mod_yours() using the helpers (section, field, status, bullet, table_begin/table_row, j). Register it in audit.sh (the _SS_MODULES list and a preset in modules_for_preset), then ./build.sh to refresh the bundle.
| Platform | Support |
|---|---|
| macOS (Apple Silicon) | ✅ Full — the primary target |
| macOS (Intel) | ✅ Full |
| Linux (NVIDIA / generic) | 🟡 Best-effort — hardware, RAM, disk, AI budget, software; battery/thermals limited |
| Windows | ❌ Use WSL (Linux path) |
Requires only Bash 3.2+ and standard Unix tools (awk, sed, df). No root, no installs.
By default the report includes your serial number and hostname (handy for your own records). Run with --share (or answer "yes" to the redaction prompt) to replace those with ‹redacted› and stamp a privacy banner — then the Markdown is safe to post publicly.
SysScope makes no network connections and writes nothing outside the report/JSON paths you choose.
Found a value that looked wrong on your machine, or want a check added (more GPUs, more models, BSD support)?
- Open an issue: https://github.com/aoneahsan/sysscope/issues — include your OS + chip + the line that looked off (no serials needed;
--shareredacts them for you). - Or fork and tweak a
mod_*.sh— it's deliberately small. After editing modules, run./build.shto refreshaudit-bundle.sh, then open a PR.
The built-in model catalog in mod_ai.sh is just data; PRs that keep model sizes current are very welcome.
MIT — see LICENSE. Use it, fork it, ship it.
SysScope is read-only and reports estimates (model sizes, speeds, and budgets are approximate and depend on quantization, context length, and other running apps). Always sanity-check before making purchasing or production decisions.