{"id":30763479,"url":"https://github.com/wsmr/macos-script-bash-health_check","last_synced_at":"2026-04-16T14:02:53.551Z","repository":{"id":311427629,"uuid":"1043659872","full_name":"wsmr/macOS-Script-Bash-health_check","owner":"wsmr","description":"🖥️ Intelligent Apple macOS system health monitoring script with actionable insights, Spotlight indexing detection, and educational guidance for system administrators","archived":false,"fork":false,"pushed_at":"2025-08-24T11:31:23.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-04T16:06:55.986Z","etag":null,"topics":["actionable-insights","bash","cpu-monitoring","diagnostics","health-check","load-analysis","macos","performance","shell-script","spotlight","system-administration","system-monitoring"],"latest_commit_sha":null,"homepage":"","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/wsmr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-24T10:53:25.000Z","updated_at":"2025-08-24T11:37:14.000Z","dependencies_parsed_at":"2025-08-24T17:09:17.352Z","dependency_job_id":"4f544902-9f9e-4d90-b430-65270c9aef32","html_url":"https://github.com/wsmr/macOS-Script-Bash-health_check","commit_stats":null,"previous_names":["wsmr/macos-script-bash-health_check"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wsmr/macOS-Script-Bash-health_check","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmr%2FmacOS-Script-Bash-health_check","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmr%2FmacOS-Script-Bash-health_check/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmr%2FmacOS-Script-Bash-health_check/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmr%2FmacOS-Script-Bash-health_check/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wsmr","download_url":"https://codeload.github.com/wsmr/macOS-Script-Bash-health_check/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wsmr%2FmacOS-Script-Bash-health_check/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31888936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["actionable-insights","bash","cpu-monitoring","diagnostics","health-check","load-analysis","macos","performance","shell-script","spotlight","system-administration","system-monitoring"],"created_at":"2025-09-04T16:03:45.762Z","updated_at":"2026-04-16T14:02:53.543Z","avatar_url":"https://github.com/wsmr.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🖥️ macOS Health Check\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![macOS](https://img.shields.io/badge/macOS-15.0+-blue.svg)](https://www.apple.com/macos/)\n[![Shell](https://img.shields.io/badge/Shell-Bash-green.svg)](https://www.gnu.org/software/bash/)\n\nA comprehensive, intelligent macOS system health monitoring script that provides actionable insights instead of just raw numbers.\n\n## 📂 Repository Structure:\n```\nmacOS-Script-Bash-health_check/\n├── macos_health_check.sh           (Main script)\n├── README.md                       (Comprehensive documentation)  \n├── LICENSE                         (MIT License)\n├── CHANGELOG.md                   📝 (Version history - Professional version history and future roadmap)\n├── examples/                      📂 (Sample outputs - Real-world output examples that users can relate to)\n│   ├── normal_system.txt         📄 (Normal system example)\n│   ├── spotlight_rebuilding.txt  📄 (Your current situation!)\n│   └── system_overload.txt       📄 (Critical system state)\n├── docs/                         📂 (Additional documentation)\n│   ├── troubleshooting.md        📋 (Comprehensive problem-solving guide)\n│   └── advanced_usage.md         🚀 (Automation, monitoring, and integration examples)\n└── .github/                      📂 (New - GitHub integration)\n    ├── ISSUE_TEMPLATE.md         🐛 (Issue reporting template -  Structured issue reporting)\n    └── workflows/\n        └── test.yml              🧪 (Basic testing - Automated testing and validation)\n```\n\n## 🌟 Features\n\n### 🧠 Intelligent Analysis\n- **Context-aware diagnostics** - Understands what's normal vs concerning\n- **Load average interpretation** with CPU core context\n- **Spotlight indexing detection** with progress tracking\n- **System process health monitoring** with escalating alerts\n- **Memory pressure analysis** with actionable thresholds\n\n### 💡 Actionable Recommendations\n- **Immediate action steps** for critical issues\n- **Timeline expectations** for temporary processes (like Spotlight rebuilding)\n- **\"Do NOT\" warnings** to prevent harmful interventions\n- **Severity-based color coding** with clear next steps\n\n### 📊 Comprehensive Coverage\n- System overview with load analysis\n- Real-time CPU usage with multi-sample accuracy\n- Spotlight/indexing status and progress\n- System process health checks\n- Memory usage analysis\n- Issue detection and classification\n- System activity context\n- Quick action guide\n\n## 🚀 Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/macOS-Script-Bash-health_check.git\ncd macos-health-check\n\n# Make the script executable\nchmod +x macos_health_check.sh\n\n# Run the health check\n./macos_health_check.sh\n```\n\n## 📋 Sample Output\n\n```\n🖥️  macOS Health Check Report\nGenerated: Sun Aug 24 16:05:35 +0530 2025\n=========================================\n📊 System Overview\nmacOS: 15.6.1\nLoad Averages: 12.28 (1m) 13.31 (5m) 11.34 (15m)\n🚨 System Load: 153% (OVERLOADED - System struggling)\n   💡 Action: Identify heavy processes, consider restart if persistent\n\n🔍 Spotlight Indexing Status\n💡 Spotlight is rebuilding index (high CPU is temporary)\n   ⏰ Expected: 30-60 minutes for completion\n   🌡️  System may be warm during this process\n   ❌ Don't interrupt: Let indexing complete naturally\n\n✅ All system processes healthy\n```\n\n## 🎯 Key Benefits\n\n### 🔍 **Smart Problem Detection**\nUnlike basic system monitors, this script:\n- **Distinguishes temporary from persistent issues**\n- **Explains WHY metrics are high** (e.g., Spotlight rebuilding)\n- **Provides context for load averages** based on your CPU core count\n- **Identifies system daemon health issues** that could indicate instability\n\n### 📚 **Educational Value**\n- **Teaches system administration concepts**\n- **Explains what metrics mean** in practical terms\n- **Builds understanding** of normal vs abnormal system behavior\n- **Prevents unnecessary panic** about temporary high loads\n\n### ⚡ **Actionable Intelligence**\n- **Immediate steps** for critical situations\n- **Monitoring guidance** for elevated metrics\n- **Timeline expectations** for ongoing processes\n- **Prevention tips** to avoid common issues\n\n## 🛠️ Requirements\n\n- **macOS 10.15+** (tested on macOS 15.6.1)\n- **Bash shell** (default on macOS)\n- **Basic command line tools** (`ps`, `df`, `uptime`, etc. - standard on macOS)\n- **Admin privileges** for some advanced checks (script will prompt when needed)\n\n## 📖 Understanding the Output\n\n### Load Average Interpretation\n```\nLoad Averages: 6.28 (1m) 6.61 (5m) 7.18 (15m)\nCPU Cores: 8\n📊 System Load: 78% (ELEVATED - Normal for active use)\n```\n- **Percentages are calculated** based on your CPU core count\n- **\u003c60% = Healthy**, **60-80% = Elevated**, **\u003e80% = High**, **\u003e100% = Overloaded**\n\n### Spotlight Status\n```\n🔍 Spotlight Indexing Status\n💡 Spotlight is rebuilding index (high CPU is temporary)\n   ⏰ Expected: 30-60 minutes for completion\n```\n- **Intensive indexing is normal** after system changes\n- **High CPU during rebuilding is expected**\n- **Process will complete automatically**\n\n### System Process Health\n```\n🔍 System Process Analysis\n✅ launchd: 0.1% CPU (NORMAL)\n❌ launchd: 26.2% CPU (HIGH)\n```\n- **System processes should typically use \u003c5% CPU**\n- **High system process CPU indicates potential issues**\n- **Multiple elevated system processes suggest restart needed**\n\n## 🚨 Common Scenarios\n\n### 🔥 High CPU from Spotlight\n**What you'll see:**\n- High load averages (\u003e100%)\n- Multiple `mds`, `mds_stores`, `mdworker_shared` processes\n- System appears to be struggling\n\n**Script guidance:**\n- ✅ Identifies this as temporary indexing\n- ⏰ Provides completion timeline\n- ❌ Warns against interrupting the process\n\n### 💾 Memory Pressure\n**What you'll see:**\n- Low memory percentage free\n- High memory usage from specific apps\n\n**Script guidance:**\n- 🎯 Identifies memory-heavy processes\n- 💡 Provides cleanup recommendations\n- ⚠️ Warns about critical memory levels\n\n### ⚡ System Daemon Issues\n**What you'll see:**\n- High CPU from system processes (launchd, logd, etc.)\n- System responsiveness issues\n\n**Script guidance:**\n- 🚨 Flags abnormal system process behavior\n- 🔧 Recommends system restart when multiple daemons affected\n- 📋 Suggests log checking commands\n\n## 🔧 Advanced Usage\n\n### Automated Monitoring\n```bash\n# Run every hour and log results\necho \"0 * * * * /path/to/macos_health_check.sh \u003e\u003e /var/log/health_check.log 2\u003e\u00261\" | crontab -\n```\n\n### Performance Tracking\n```bash\n# Create timestamped reports\n./macos_health_check.sh \u003e \"health_report_$(date +%Y%m%d_%H%M%S).txt\"\n```\n\n### Integration with Monitoring Systems\nThe script's structured output can be parsed by monitoring systems or log aggregators.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. Some areas where contributions would be especially valuable:\n\n- 🎯 **Additional system checks** (disk health, network status, etc.)\n- 🎨 **Output format options** (JSON, CSV, etc.)\n- 🔧 **Integration helpers** for monitoring systems\n- 📚 **Documentation improvements**\n- 🌍 **Localization** for different languages\n\n### Development Setup\n```bash\ngit clone https://github.com/macOS-Script-Bash-health_check.git\ncd macos-health-check\n\n# Test your changes\n./macos_health_check.sh\n\n# Run with different scenarios to test logic\n```\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by the need for **intelligent system monitoring** beyond basic metrics\n- Built for **macOS system administrators** who need actionable insights\n- Designed to **educate users** about their system's behavior\n\n## ⭐ Star History\n\nIf this script helped you understand and fix your macOS performance issues, please consider giving it a star! ⭐\n\n## 📞 Support\n\n- 🐛 **Bug reports**: [Open an issue](https://github.com/macOS-Script-Bash-health_check/issues)\n- 💡 **Feature requests**: [Start a discussion](https://github.com/macOS-Script-Bash-health_check/discussions)\n- 📖 **Questions**: Check existing issues or start a new discussion\n\n---\n\n**Made with ❤️ for macOS power users and system administrators**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwsmr%2Fmacos-script-bash-health_check","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwsmr%2Fmacos-script-bash-health_check","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwsmr%2Fmacos-script-bash-health_check/lists"}