Metadata-Version: 2.4
Name: macmonica
Version: 1.0.0
Summary: Lightweight macOS system health monitor with historical tracking, smart alerts, and actionable insights — Monica would be proud of how clean your system runs
Author: Hritik Valluvar
License: MIT
Project-URL: Homepage, https://github.com/hritikvalluvar/macmonica
Project-URL: Issues, https://github.com/hritikvalluvar/macmonica/issues
Keywords: macos,system-monitor,battery,health,performance,terminal,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Requires-Dist: rich>=13.0
Dynamic: license-file

# macmonica

A lightweight macOS system health monitor that tracks metrics over time, sends smart alerts, and tells you exactly what's draining your resources.

**What makes it different from htop/btop/glances:** Those are live-only dashboards. macmonica tracks history, predicts battery degradation, groups processes by app, sends macOS notifications, and tells you *why* your Mac is slow — not just *that* it's slow.

## Install

```bash
pip install macmonica
```

After install, the CLI command is `macmonica`:

```bash
macmonica doctor
```

## Quick Start

```bash
# Start the background collector (gathers data every 60s)
macmonica collect &

# Or install as a launchd service (auto-starts on login)
bash setup.sh

# See what's happening right now
macmonica why

# Live dashboard
macmonica

# What drained my battery?
macmonica blame
```

## Commands

### Real-time

| Command | Description |
|---------|-------------|
| `macmonica` | Live dashboard with process grouping, energy impact, battery health |
| `macmonica doctor` | Full system health check with pass/fail/warn verdicts |
| `macmonica why` | Plain English explanation of what's wrong |
| `macmonica top [--sort cpu\|mem\|energy]` | Grouped process list (like top, but useful) |
| `macmonica recommend` | Actionable recommendations based on current state |

### Battery & Power

| Command | Description |
|---------|-------------|
| `macmonica blame [--hours N]` | Correlates battery drain with top CPU consumers |
| `macmonica wake-log` | Shows wake/sleep events — catches phantom drain |
| `macmonica usb` | Connected USB devices and their power draw |

### Historical

| Command | Description |
|---------|-------------|
| `macmonica history [--period 24h\|7d\|30d]` | Sparkline trends with color-coded alert zones |
| `macmonica compare 24h 7d` | Side-by-side period comparison |
| `macmonica report [--period week\|month]` | Full health report with daily breakdown |
| `macmonica digest [--today] [--notify]` | Daily summary with optional macOS notification |
| `macmonica alerts` | Alert history log |

### Data & Config

| Command | Description |
|---------|-------------|
| `macmonica export [--period 24h\|7d\|30d\|all] [-o file.csv]` | Export to CSV |
| `macmonica status` | Collector status, DB size, last snapshot time |
| `macmonica config [--init]` | View or create configuration |
| `macmonica collect` | Run collector daemon (for launchd) |
| `macmonica collect-once` | Single snapshot (for testing) |

## Features

### Smart Alerts (macOS notifications)
- CPU sustained above threshold
- Memory/disk usage critical
- Battery health degraded
- WiFi signal weak
- Disk I/O rate abnormal
- **Anomaly detection** — alerts when metrics deviate from your 7-day baseline
- **Quiet hours** — no notifications between 11pm-7am (configurable)

### Battery Intelligence
- Tracks cycle count, max capacity, and condition over time
- Predicts when battery will hit 75% health
- `blame` command tells you exactly what drained your battery
- Wake/sleep log catches phantom drain from DarkWake events

### Process Grouping
Chrome's 30 helper processes show as one "Chrome" row with aggregated CPU/memory. Same for Safari, VS Code, Slack, Firefox, and any Electron app.

### Webhooks
Send alerts to Slack, Discord, or ntfy.sh:
```json
{
  "webhook_url": "https://ntfy.sh/your-topic"
}
```

### Auto-Actions
Configure automatic responses to conditions:
```json
{
  "auto_actions": [
    {
      "condition": {"metric": "cpu_avg", "op": ">", "value": 95},
      "action": "notify",
      "message": "CPU critical"
    }
  ]
}
```

## Configuration

Config lives at `~/.macmonica/config.json`. Create defaults with:

```bash
macmonica config --init
```

Key settings:
- `collect_interval`: Seconds between snapshots (default: 60, min: 10)
- `retention_days`: How long to keep data (default: 30)
- `quiet_hours`: `{"enabled": true, "start": 23, "end": 7}`
- `webhook_url`: URL for alert webhooks
- `auto_actions`: List of automated response rules
- `alerts`: Per-alert-type thresholds and enable/disable

## Resource Usage

The background collector is designed to be invisible:
- **CPU**: ~0.26s per collection cycle, then sleeps 60s
- **Memory**: ~28MB (Python + psutil baseline)
- **Disk**: ~1MB/month of SQLite data
- **No subprocess calls** in the hot path (battery/thermal cached 5min, WiFi cached 1min)

## Data Storage

All data is stored locally in `~/.macmonica/macmonica.db` (SQLite). Nothing is sent anywhere unless you configure a webhook.

## Requirements

- macOS (Apple Silicon or Intel)
- Python 3.10+

## License

MIT
