Skip to content

Byte AlShams

Mac System Health Assistant This project proposes the development of a Mac System Health Assistant, a lightweight local assistant that monitors system telemetry, diagnoses common performance problems, and provides clear

Code Video Cerebral Valley

Core trick

Runs deterministic macOS telemetry diagnosis first, with an optional LLM layer that explains results and three execution modes gating any remediation.

Tags

dev toolsproductivity

Description

Mac System Health Assistant This project proposes the development of a Mac System Health Assistant, a lightweight local assistant that monitors system telemetry, diagnoses common performance problems, and provides clear explanations and safe remediation suggestions.
lcipolina/mac_system_health_assistant★ 00 forksPythonCreated Mar 21, 2026 · last push Mar 21, 2026

README excerpt

# Mac System Health Assistant

Local macOS system diagnostics assistant with:

- deterministic observability and diagnosis
- LLM-assisted explanation layer (optional)
- mode-based safety model:
  - `diagnose` (Mode A)
  - `guided` (Mode B)
  - `safe-exec` (Mode C)

## Quick Start

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Optional LLM setup:

```bash
cp .env.example .env
# Edit .env and set provider + API key.
# Model defaults are in config/models.json
```

Run commands:

```bash
msha snapshot --json
msha diagnose --json
msha report --mode diagnose
msha explain "Why is my Mac slow?"
msha actions list --mode guided
```

GUI widget:

```bash
pip install -e ".[gui]"
msha-widget
```

## Safety Notes

- `diagnose` mode is the default and executes no remediation commands.
- `guided` mode allows non-impactful open actions only.
- `safe-exec` mode allows only whitelisted actions and enforces confirmation for impactful actions.
- All action attempts and outcomes are audit logged.

## LLM Backend Config

- Secrets: `.env` (never committed)
- Model/runtime defaults: `config/models.json`
- Supported OpenAI-compatible providers in this build:
  - `gemini`
  - `huggingface`
  - `openai`
  - `openrouter`
  - `groq`
  - `together`
  - `fireworks`
  - `mistral`
- Fallback behavior:
  - if LLM is disabled or fails, deterministic template explanation is used

See [docs/LLM_BACKEND.md](docs/LLM_BACKEND.md) for full backend setup details.

## Backend Arc

Team