{"id":29085189,"url":"https://github.com/open-technology-foundation/syshealth","last_synced_at":"2025-06-27T22:32:15.572Z","repository":{"id":300140966,"uuid":"1005252017","full_name":"Open-Technology-Foundation/syshealth","owner":"Open-Technology-Foundation","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-20T03:10:01.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T04:21:56.306Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-06-19T23:48:53.000Z","updated_at":"2025-06-20T03:10:05.000Z","dependencies_parsed_at":"2025-06-20T04:32:30.053Z","dependency_job_id":null,"html_url":"https://github.com/Open-Technology-Foundation/syshealth","commit_stats":null,"previous_names":["open-technology-foundation/syshealth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Open-Technology-Foundation/syshealth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fsyshealth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fsyshealth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fsyshealth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fsyshealth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/syshealth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fsyshealth/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262343641,"owners_count":23296367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-06-27T22:30:57.107Z","updated_at":"2025-06-27T22:32:15.563Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SysHealth - AI-Powered System Health Monitor\n\nSysHealth is a comprehensive Linux system health monitoring tool that combines traditional system information gathering with advanced AI analysis. It examines local or remote systems, collects detailed hardware and performance data, and uses Claude AI to generate intelligent health reports with actionable insights and recommendations.\n\n## Features\n\n- **Comprehensive System Analysis**: Collects hardware, storage, memory, CPU, network, and security information\n- **AI-Powered Insights**: Uses Claude AI to analyze data and identify potential issues\n- **Multi-Host Support**: Analyze multiple systems simultaneously \n- **Remote Analysis**: Monitor remote systems via SSH (key-based authentication)\n- **Multi-Language Reports**: Generate reports in multiple languages\n- **Flexible Output**: Markdown reports with optional email delivery\n- **Modular Architecture**: Extensible collector-based design\n- **YAML Configuration**: Centralized configuration with environment variable overrides\n- **Debug Mode**: Detailed logging and troubleshooting capabilities\n\n## Requirements\n\n- **Operating System**: Ubuntu/Debian Linux (primary), other distributions supported\n- **Python**: Version 3.8+ (3.12+ recommended)\n- **API Key**: Anthropic API key for Claude AI analysis\n- **SSH Access**: For remote host analysis (key-based authentication required)\n\n### System Dependencies\n\n**Required:**\n- `python3` - Core runtime\n\n**Recommended (for optimal functionality):**\n- `lshw` - Hardware information listing\n- `df` - Disk space usage\n- `ps` - Process information\n- `free` - Memory usage\n- `lsblk` - Block device listing\n- `ss` or `netstat` - Network statistics\n\n**Optional (for enhanced features):**\n- `pandoc` - Email HTML conversion\n- `smartctl` - Disk health monitoring\n- `chkrootkit` - Security scanning\n\n## Installation\n\n### Automated Installation (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/syshealth.git\ncd syshealth\n\n# Install system-wide (requires sudo)\nsudo ./install.sh\n```\n\nThe installer will:\n1. Copy files to `/usr/local/syshealth`\n2. Create symlink in `/usr/local/bin/syshealth`\n3. Set up Python virtual environment\n4. Install Python dependencies\n\n### Manual Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/syshealth.git\ncd syshealth\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Make scripts executable\nchmod +x syshealth syshealth.py\n```\n\n## Configuration\n\n### API Key Setup\n\nSet your Anthropic API key as an environment variable:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key-here\"\n```\n\nFor persistent use, add to your `~/.bashrc` or `~/.profile`.\n\n### Configuration File\n\nSysHealth uses a YAML configuration file located at `config/syshealth.yaml`. Key settings include:\n\n- **Claude Model**: Default AI model (`claude-sonnet-4-0`)\n- **Report Thresholds**: Warning and critical levels for disk, memory, CPU\n- **Output Settings**: File formats, directories, naming patterns\n- **Email Configuration**: SMTP settings for report delivery\n- **Command Timeouts**: Execution limits for system commands\n\nSettings can be overridden with environment variables using the format:\n`SYSHEALTH_\u003csection\u003e_\u003ckey\u003e` (e.g., `SYSHEALTH_CLAUDE_MODEL`)\n\n## Usage\n\n### Basic Usage\n\n```bash\n# Analyze local system with verbose output\nsyshealth -v\n\n# Analyze remote host\nsyshealth -v remote-server\n\n# Analyze multiple hosts with Spanish reports\nsyshealth -v -L spanish server1 server2 server3\n\n# Custom output directory\nsyshealth -v -o /path/to/reports hostname\n```\n\n### Command-Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-v, --verbose` | Enable verbose output (show reports in terminal) | `false` |\n| `-d, --debug` | Enable debug mode (save API prompts and details) | `false` |\n| `-L, --language LANG` | Report language | `en` |\n| `-m, --model MODEL` | Claude model to use | `claude-sonnet-4-0` |\n| `-o, --output-dir DIR` | Report output directory | `~/syshealth` |\n| `--mail EMAILS` | Comma-separated email recipients | `none` |\n| `hosts` | Space-separated list of hosts to analyze | `current host` |\n\n### Email Reports\n\nSend reports via email using local SMTP:\n\n```bash\n# Single recipient\nsyshealth -v --mail admin@example.com server1\n\n# Multiple recipients\nsyshealth -v --mail \"admin@example.com,ops@example.com\" server1 server2\n```\n\n### Debug Mode\n\nEnable debug mode for troubleshooting:\n\n```bash\nsyshealth -d -v hostname\n```\n\nDebug files are saved to `reports/debug/` and include:\n- Full prompts sent to Claude API\n- Command execution timings\n- API response metadata\n\n## Report Structure\n\nGenerated reports include the following sections:\n\n1. **System Overview** - Hostname, OS version, uptime, basic status\n2. **Hardware Configuration** - CPU, memory, storage components\n3. **Storage Status** - Disk usage, mount points, filesystem health\n4. **Memory Usage** - RAM and swap utilization and allocation\n5. **CPU Performance** - Load averages, top processes, bottlenecks\n6. **Network Configuration** - Interfaces, listening ports, connections\n7. **System Health** - Failed services, logs, authentication issues\n8. **Critical Issues** - High-priority problems requiring immediate attention\n9. **Warnings** - Potential issues that aren't yet critical\n10. **Recommendations** - Specific improvement suggestions\n\nReports are saved as markdown files with format: `hostname-language-timestamp.md`\n\n## Architecture\n\nSysHealth uses a modular architecture for maintainability and extensibility:\n\n### Core Components\n\n- **Main Script** (`syshealth.py`) - Entry point and workflow orchestration\n- **Claude Client** (`claude_client.py`) - AI API integration\n- **Collectors** - Specialized system information gathering modules\n- **Executors** - Command execution abstraction (local/remote)\n- **Configuration** - YAML-based settings management\n\n### Collectors\n\n- `BasicSystemInfoCollector` - OS, hostname, uptime\n- `HardwareInfoCollector` - CPU, memory, hardware listing\n- `StorageInfoCollector` - Disks, filesystems, health\n- `ProcessInfoCollector` - Running processes, resource usage\n- `NetworkInfoCollector` - Interfaces, ports, connectivity\n- `SecurityInfoCollector` - Services, logs, updates, security checks\n\n### Executors\n\n- `LocalCommandExecutor` - Local command execution\n- `RemoteCommandExecutor` - SSH-based remote execution\n\n## Development\n\n### Running Tests\n\n```bash\n# Install test dependencies\npip install pytest pytest-cov pytest-mock\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=syshealth\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack .\n\n# Check style\nflake8\n\n# Sort imports\nisort .\n```\n\n### Project Structure\n\n```\nsyshealth/\n├── syshealth.py           # Main application entry point\n├── claude_client.py       # Claude AI integration\n├── syshealth              # Bash wrapper script\n├── install.sh             # Installation script\n├── requirements.txt       # Python dependencies\n├── config/                # Configuration management\n│   ├── syshealth.yaml    # Main configuration file\n│   └── *.py              # Config modules\n├── collectors/            # System information collectors\n├── executors/             # Command execution abstractions\n├── tests/                 # Unit tests\n└── reports/              # Generated health reports\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**API Key Errors:**\n- Verify `ANTHROPIC_API_KEY` is set: `echo $ANTHROPIC_API_KEY`\n- Ensure API key is valid and has sufficient credits\n\n**SSH Connection Failures:**\n- Verify SSH key-based authentication is configured\n- Test SSH access: `ssh hostname`\n- Check SSH permissions and host key verification\n\n**Missing Dependencies:**\n- Install recommended packages: `sudo apt-get install lshw df ps free lsblk`\n- Check dependency status in verbose mode\n\n**Virtual Environment Issues:**\n- Recreate environment: `rm -rf .venv \u0026\u0026 python3 -m venv .venv`\n- Reinstall dependencies: `source .venv/bin/activate \u0026\u0026 pip install -r requirements.txt`\n\n### Debug Information\n\nUse debug mode (`-d`) to troubleshoot issues:\n- API communication problems\n- Command execution failures\n- Configuration issues\n- Performance bottlenecks\n\nDebug files are saved to `reports/debug/` with detailed information about:\n- Prompts sent to Claude API\n- Command execution timings\n- Error messages and stack traces\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Run code quality checks\n5. Submit a pull request\n\nFor development setup and contribution guidelines, see `CLAUDE.md`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fsyshealth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fsyshealth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fsyshealth/lists"}