{"id":51029015,"url":"https://github.com/aoneahsan/sysscope","last_synced_at":"2026-06-21T22:03:41.752Z","repository":{"id":363305620,"uuid":"1262745111","full_name":"aoneahsan/sysscope","owner":"aoneahsan","description":"🔭 Audit your Mac/Linux machine and instantly see which local AI models (Ollama) and CPU/GPU dev workloads it can actually run — model-by-model fit verdict, health scorecard, privacy redaction, zero installs (npx).","archived":false,"fork":false,"pushed_at":"2026-06-08T09:37:59.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T11:22:05.933Z","etag":null,"topics":["ai-readiness","apple-silicon","cli","gpu","hardware","llm","local-ai","macos","ollama","system-audit"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aoneahsan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-bundle.sh","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-08T09:27:03.000Z","updated_at":"2026-06-08T09:38:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aoneahsan/sysscope","commit_stats":null,"previous_names":["aoneahsan/sysscope"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/aoneahsan/sysscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoneahsan%2Fsysscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoneahsan%2Fsysscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoneahsan%2Fsysscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoneahsan%2Fsysscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aoneahsan","download_url":"https://codeload.github.com/aoneahsan/sysscope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aoneahsan%2Fsysscope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34627255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-readiness","apple-silicon","cli","gpu","hardware","llm","local-ai","macos","ollama","system-audit"],"created_at":"2026-06-21T22:03:41.178Z","updated_at":"2026-06-21T22:03:41.747Z","avatar_url":"https://github.com/aoneahsan.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔭 SysScope — System Capability \u0026 AI-Readiness Audit\n\n**[GitHub repo](https://github.com/aoneahsan/sysscope)** · **[Gist mirror](https://gist.github.com/aoneahsan/d55e9709334ef5723468ad44fa667c6d)** · run it instantly: `npx sysscope`\n\nA small, **modular, read-only** shell tool that audits any Mac (and most Linux boxes) and tells you, in plain language:\n\n- **What hardware you have** — CPU, GPU, Neural Engine, RAM, storage, battery, thermals\n- **What dev \u0026 AI software is installed** — languages, package managers, containers, VMs, LLM tooling\n- **Which local AI models you can actually run** — a model-by-model \"fits / tight / too big\" verdict tuned to *your* memory\n- **What to run together** — a health scorecard and concurrency advice so you don't blow your RAM budget\n\nIt prints a colorized terminal report **and** writes a shareable Markdown report (plus optional JSON). It never changes your system — it only reads.\n\n\u003e 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?\"*\n\n**▶ Try it now (no install):**\n\n```bash\nnpx sysscope\n```\n\n---\n\n## ✨ Features\n\n- 🧠 **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.\n- 🖥️ **Real hardware detection** — Apple Silicon core layout, GPU cores, Metal version, NVIDIA VRAM, disk pressure, battery health, thermal throttling.\n- 🩺 **Health scorecard** — disk / memory / AI / battery rated 🟢🟡🟥 with one-line reasons.\n- 🧩 **Modular** — one job per file (`lib_*`, `mod_*`). Easy to read, extend, or trim.\n- 📦 **Single-file bundle** — `build.sh` concatenates everything into `audit-bundle.sh` for `curl | bash` distribution.\n- 🔒 **Privacy mode** — `--share` redacts serials, UUIDs, and hostname so you can post the report publicly.\n- 🤝 **Interactive or unattended** — menu-driven by default, fully scriptable with flags.\n- 📄 **Multiple outputs** — pretty terminal, Markdown report, and machine-readable JSON.\n- 🐚 **Portable** — pure Bash, compatible with the **bash 3.2** that ships on macOS (no extra installs).\n\n---\n\n## 🚀 Quick start\n\n### Option A — run it with `npx` (no install, no clone) ⭐\n\n```bash\nnpx sysscope\n```\n\nThat'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:\n\n```bash\nnpx sysscope --ai-only      # \"which models can I run?\"\nnpx sysscope --quick --yes  # fast, unattended\nnpx sysscope --share        # redacted, shareable report\n```\n\n\u003e Needs Node (for `npx`) and `bash` (built in on macOS/Linux; use WSL/Git Bash on Windows). The launcher only runs the local audit — it makes no network calls.\n\u003e\n\u003e Want the very latest (unreleased) version straight from `main`? Use `npx github:aoneahsan/sysscope`.\n\n### Option B — clone the repo (modular version)\n\n```bash\ngit clone https://github.com/aoneahsan/sysscope.git\ncd sysscope\nchmod +x audit.sh\n./audit.sh\n```\n\n### Option C — single file, no Node\n\n```bash\n# Download just the self-contained bundle and run it\ncurl -fsSLO https://raw.githubusercontent.com/aoneahsan/sysscope/main/audit-bundle.sh\nbash audit-bundle.sh\n\n# …or pipe it (always review remote scripts first!):\ncurl -fsSL https://raw.githubusercontent.com/aoneahsan/sysscope/main/audit-bundle.sh | bash\n```\n\n---\n\n## 🕹️ Usage\n\n```text\n./audit.sh [options]\n\nPRESETS\n  -f, --full         Full audit (default)\n  -q, --quick        Faster: skips software inventory \u0026 deep disk scan\n  -a, --ai-only      Just \"what AI models can I run?\"\n\nOUTPUT\n  -o, --output FILE  Markdown report path (default: ./sysscope-report-\u003ctimestamp\u003e.md)\n      --no-report    Terminal only\n      --json [FILE]  Also write JSON metrics\n      --deep         Include slow probes (largest items in home folder)\n\nPRIVACY\n      --share        Redact serials / UUIDs / hostname (safe to publish)\n\nBEHAVIOR\n  -y, --yes          Non-interactive (accept defaults)\n      --no-color     Disable colors\n      --gist-url URL Feedback URL printed in the report\n  -V, --version      Print version\n  -h, --help         Show help\n```\n\n### Examples\n\n```bash\n./audit.sh                       # interactive, full audit, saves a report\n./audit.sh --quick --yes         # fast, unattended\n./audit.sh --ai-only             # which models fit?\n./audit.sh --share -o report.md  # redacted, shareable\n./audit.sh --json metrics.json   # full audit + JSON metrics\n```\n\n---\n\n## 📟 Sample output (excerpt, redacted)\n\n```text\n== Local AI / LLM Capability ==\n  Inference backend      unified memory (Metal GPU shares 16 GB)\n  Usable memory budget   ~11.5 GB for the model + context\n  Capability tier        Comfortable — 7–9B daily (14B tight)\n  [OK ] Hardware-accelerated local inference is available.\n\n  Which models fit (Ollama, Q4 quantization)\n  MODEL                  PARAMS  ~SIZE     FITS?\n  llama3.1:8b            8B      4.7GB     ✅ yes\n  qwen2.5-coder:7b       7B      4.7GB     ✅ yes\n  gemma2:9b              9B      5.4GB     ✅ yes\n  qwen2.5:14b            14B     9.0GB     🟡 tight\n  gemma2:27b             27B     16.0GB    🔴 too big\n\n== Health Scorecard \u0026 Recommendations ==\n  Disk             🟥 critical  Only 19 GB free — reclaim before installing tools.\n  Memory           🟢 good      16 GB — one very-heavy workload at a time.\n  Local AI         🔭           Comfortable — 7–9B daily (14B tight) (~11.5 GB budget)\n```\n\nThe Markdown report contains the same content as GFM tables, ready to paste into an issue, wiki, or gist comment.\n\n---\n\n## 🧠 How the AI capability engine works\n\n1. **Find the memory budget** that matters for inference:\n   - **NVIDIA GPU** → ~92% of VRAM (`nvidia-smi`).\n   - **Apple Silicon** → `total RAM − 4.5 GB` (the GPU shares unified memory; the rest is for macOS + a couple of apps).\n   - **CPU-only** → `total RAM − 3 GB`, with a \"this will be slow\" warning.\n2. **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*.\n3. **Pick a tier** (Minimal → Workstation) and print a tailored **starter set** plus install commands.\n\nGeneration speed is memory-bandwidth-bound, so the tool gives qualitative tok/s ranges rather than false precision.\n\n\u003e 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.\n\n---\n\n## 🧩 Project structure\n\nEach file does one thing and is sourced by `audit.sh`:\n\n| File | Responsibility |\n|------|----------------|\n| `audit.sh` | Entry point: arg parsing, interactive menu, orchestration |\n| `lib_core.sh` | Output/formatting, OS detection, prompts, helpers |\n| `lib_report.sh` | Markdown + JSON document lifecycle, tables |\n| `mod_system.sh` | OS, model, chip, kernel identity |\n| `mod_cpu.sh` | CPU topology (P/E cores) |\n| `mod_memory.sh` | RAM, swap, pressure |\n| `mod_gpu.sh` | GPU, unified vs discrete VRAM, accelerators |\n| `mod_storage.sh` | Disk capacity, free space, biggest items |\n| `mod_power.sh` | Battery health, charge, thermal throttling |\n| `mod_software.sh` | Languages, package managers, containers, AI tooling |\n| `mod_ai.sh` | **Local-AI capability assessment** |\n| `mod_recommend.sh` | Health scorecard + workload guidance |\n| `build.sh` | Bundles all of the above into `audit-bundle.sh` |\n\n### Extending it\n\nAdd 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.\n\n---\n\n## 💻 Compatibility\n\n| Platform | Support |\n|----------|---------|\n| macOS (Apple Silicon) | ✅ Full — the primary target |\n| macOS (Intel) | ✅ Full |\n| Linux (NVIDIA / generic) | 🟡 Best-effort — hardware, RAM, disk, AI budget, software; battery/thermals limited |\n| Windows | ❌ Use WSL (Linux path) |\n\nRequires only **Bash 3.2+** and standard Unix tools (`awk`, `sed`, `df`). No root, no installs.\n\n---\n\n## 🔒 Privacy\n\nBy 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.\n\nSysScope makes **no network connections** and **writes nothing outside** the report/JSON paths you choose.\n\n---\n\n## 💬 Feedback \u0026 contributing\n\nFound a value that looked wrong on your machine, or want a check added (more GPUs, more models, BSD support)?\n\n- Open an issue: https://github.com/aoneahsan/sysscope/issues — include your **OS + chip + the line that looked off** (no serials needed; `--share` redacts them for you).\n- Or fork and tweak a `mod_*.sh` — it's deliberately small. After editing modules, run `./build.sh` to refresh `audit-bundle.sh`, then open a PR.\n\nThe built-in model catalog in `mod_ai.sh` is just data; PRs that keep model sizes current are very welcome.\n\n---\n\n## 📜 License\n\nMIT — see [`LICENSE`](./LICENSE). Use it, fork it, ship it.\n\n---\n\n## ⚠️ Disclaimer\n\nSysScope 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoneahsan%2Fsysscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faoneahsan%2Fsysscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faoneahsan%2Fsysscope/lists"}