{"id":32541119,"url":"https://github.com/fluidinference/fluidtop","last_synced_at":"2025-10-28T15:57:45.084Z","repository":{"id":301633871,"uuid":"1009829313","full_name":"FluidInference/fluidtop","owner":"FluidInference","description":"MacOS hardware performance monitoring CLI tool with a focus on AI Workloads","archived":false,"fork":false,"pushed_at":"2025-07-07T03:18:14.000Z","size":7545,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-25T04:34:07.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","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/FluidInference.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-27T19:35:55.000Z","updated_at":"2025-09-22T06:59:32.000Z","dependencies_parsed_at":"2025-06-27T22:35:39.631Z","dependency_job_id":"604794b8-588c-42e5-afae-d9c88e763e58","html_url":"https://github.com/FluidInference/fluidtop","commit_stats":null,"previous_names":["fluidinference/fluidtop"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FluidInference/fluidtop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FluidInference%2Ffluidtop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FluidInference%2Ffluidtop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FluidInference%2Ffluidtop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FluidInference%2Ffluidtop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FluidInference","download_url":"https://codeload.github.com/FluidInference/fluidtop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FluidInference%2Ffluidtop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281467277,"owners_count":26506462,"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","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"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":[],"created_at":"2025-10-28T15:57:40.363Z","updated_at":"2025-10-28T15:57:45.062Z","avatar_url":"https://github.com/FluidInference.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FluidTop - MacOS Performance Monitor for Local AI\n\n[![PyPI version](https://badge.fury.io/py/fluidtop.svg)](https://badge.fury.io/py/fluidtop)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![macOS](https://img.shields.io/badge/macOS-Monterey%2B-green.svg)](https://www.apple.com/macos/)\n[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-M1%2FM2%2FM3%2FM4-orange.svg)](https://www.apple.com/mac/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Real-time macOS hardware performance monitoring CLI tool for Apple Silicon Macs (M1/M2/M3/M4+) with AI workload focus**\n\nFluidTop is a Python-based `nvtop`-inspired command line tool specifically designed for Apple Silicon Macs. This enhanced and actively maintained fork of the original [asitop](https://github.com/tlkh/asitop) project provides comprehensive hardware monitoring with additional features, support for newer Apple Silicon chips, and optimizations for modern terminal emulators including Ghostty.\n\n![View animated demo (GIF)](https://raw.githubusercontent.com/FluidInference/fluidtop/main/images/live.gif)\n\n## 📦 Installation \u0026 Usage\n\n### Quick Start with UV (Recommended)\n\n```bash\n# Install UV package manager (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n```bash\n# Run FluidTop directly without installation (one-time usage)\nsudo uvx fluidtop\n\n# Run with custom options\nsudo uvx fluidtop --interval 2 --color 5 --avg 60\n\n# Or install as a tool for regular usages\nuv tool install fluidtop@latest -U\nsudo uv tool run fluidtop\n```\n\n```bash\n# to update fluidtop\nuv tool install fluidtop@latest -U\n```\n\n```bash\n# Run with custom options\nsudo uvx fluidtop --interval 2 --color 5 --avg 60\n```\n\n### Install from PyPI\n\n```bash\n# Install with pip\npip install fluidtop\n\n# Run after installation\nsudo fluidtop\n```\n\n## 🚀 Key Features \u0026 Capabilities\n\n### Hardware Monitoring\n* **Real-time CPU monitoring** - Individual core utilization and frequency tracking\n* **GPU performance tracking** - Apple GPU usage, memory, and power consumption  \n* **Neural Engine (ANE) monitoring** - AI/ML workload detection and utilization\n* **Memory usage monitoring** - RAM and swap memory tracking\n* **Power consumption analysis** - CPU/GPU power draw with thermal throttling detection\n* **Temperature monitoring** - System thermal state and throttling alerts\n\n### Apple Silicon Support\n* **Complete Apple Silicon coverage** - M1, M2, M3, M4, and future chip support\n* **Optimized for modern terminals** - Enhanced Ghostty compatibility and performance\n* **Hardware-specific metrics** - TDP specifications for all variants\n* **Individual core monitoring** - Detailed per-core performance and efficiency tracking\n\n### AI \u0026 Machine Learning Focus\n* **AI workload detection** - Specialized monitoring for machine learning tasks\n* **Neural Engine utilization** - Track AI inference and training workloads\n* **Memory usage optimization** - Critical for large model performance\n* **Future ML framework integration** - Planned support for popular AI libraries\n\n### Development Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/FluidInference/fluidtop.git\ncd fluidtop\n\n# Install in development mode\nuv sync\nsudo uv run fluidtop\n```\n\n## 🎛️ Command Line Options \u0026 Configuration\n\n```bash\nfluidtop [OPTIONS]\n\nOptions:\n  --interval INTERVAL   Display refresh rate in seconds (default: 1.0)\n  --color COLOR        Color theme selection 0-8 (default: 2)\n  --avg AVG           Power averaging window in seconds (default: 30)\n  --show_cores        Enable individual CPU core monitoring\n  --max_count COUNT   Restart powermetrics after N samples (stability)\n  -h, --help          Show help message and exit\n```\n\n### Usage Examples\n\n```bash\n# Basic monitoring with 1-second refresh\nsudo fluidtop\n\n# High-frequency monitoring for AI workloads\nsudo fluidtop --interval 0.5 --show_cores\n\n# Long-term monitoring with 60-second power averaging\nsudo fluidtop --avg 60 --max_count 1000\n\n# Custom color theme\nsudo fluidtop --color 5\n```\n\n## 🔧 How FluidTop Works\n\nFluidTop leverages macOS's built-in [`powermetrics`](https://www.unix.com/man-page/osx/1/powermetrics/) utility to access hardware performance counters with minimal system impact. Root privileges are required due to `powermetrics` security requirements.\n\n### Technical Architecture\n\n* **CPU/GPU Utilization:** Active residency measurements via `powermetrics`\n* **Power Consumption:** Hardware energy counters and thermal state monitoring\n* **Memory Statistics:** [`psutil`](https://github.com/giampaolo/psutil) virtual memory and swap tracking\n* **System Information:** `sysctl` CPU details and `system_profiler` GPU specifications\n* **Hardware Database:** Built-in TDP specifications for all Apple Silicon variants\n\n**Note**: Bandwidth monitoring was removed as macOS 13 deprecated bandwidth support in powermetrics.\n\n### System Requirements\n\n* **Hardware:** Apple Silicon Mac (M1, M2, M3, M4, or newer)\n* **Operating System:** macOS Monterey (12.0) or later\n* **Python:** Python 3.8+ (automatically managed with UV)\n* **Privileges:** Root access required for `powermetrics`\n\n### Why Fork asitop?\n\nThe original `asitop` provided excellent Apple Silicon monitoring but lacked:\n\n- **Modern hardware support** - M3, M4+ compatibility\n- **Terminal compatibility** - Ghostty and modern terminal optimization  \n- **AI workload focus** - Machine learning specific monitoring\n- **Active maintenance** - Regular updates and bug fixes\n\n### Migration from asitop\n\nFluidTop is a drop-in replacement for asitop with identical command-line interface:\n\n```bash\n# Replace this:\nsudo asitop\n\n# With this:\nsudo fluidtop\n```\n\n## 📚 Documentation\n\nFor detailed information, troubleshooting, and frequently asked questions, see our comprehensive [FAQ](docs/FAQ.md) which covers:\n\n- **Apple Silicon Architecture**: Understanding E-CPU vs P-CPU cores\n- **System Requirements**: Supported chips and compatibility  \n- **Monitoring Details**: Power accuracy, Neural Engine tracking, and more\n- **Troubleshooting**: Common issues and solutions\n- **Migration Guide**: Differences from asitop and compatibility\n\n## 🗺️ Roadmap \u0026 Development\n\n### Completed Features\n- ✅ Enhanced hardware support (M1-M4+)\n- ✅ Ghostty terminal optimization  \n- ✅ Improved documentation and user experience\n- ✅ PyPI publishing and UV integration\n\n### In Development\n- 🔄 monitor a specific process/application\n- 🔄 GUI-less monitoring and data collection\n- 🔄 Performance data export capabilities (CSV, JSON)\n- API interface for other Python services\n\n## 🛠️ Development \u0026 Publishing\n\n### Automated Release Process\n\nFluidTop uses GitHub Actions to automate the entire release process. No manual steps required!\n\n#### 🧪 Development Workflow\n\n```bash\n# Setup development environment\ngit clone https://github.com/FluidInference/fluidtop.git\ncd fluidtop\nuv sync\n\n# Make changes to code\n# Test changes locally\nsudo uv run fluidtop\n\n# Run with development options\nsudo uv run fluidtop --interval 0.5 --show_cores\n\n# Test build (optional)\nuv build\nsudo uv run fluidtop --help  # Verify build works\n```\n\n\n## 🐛 Known Issues \u0026 Contributing\n\n### Current Issues\n- Chart height doesn't adapt to terminal height (width works correctly)\n- Plot colors don't always respect theme selection\n- Long-running sessions may require periodic restart\n\n### Contributing\n- Report bugs and request features via [GitHub Issues](https://github.com/FluidInference/fluidtop/issues)\n- Submit pull requests for bug fixes and improvements\n- Improve documentation and examples\n- Test on different Apple Silicon variants\n\n## 📄 License\n\nMIT License - maintaining compatibility with the original asitop project.\n\n## 🙏 Acknowledgments\n\nThis project builds upon the excellent foundation created by [Timothy Liu](https://github.com/tlkh) with the original [asitop](https://github.com/tlkh/asitop) project. We extend our gratitude for creating the groundwork for Apple Silicon performance monitoring.\n\n---\n\n**Keywords:** Apple Silicon monitoring, M1 M2 M3 M4 performance, macOS system monitor, AI workload tracking, Neural Engine monitoring, GPU utilization, real-time hardware stats, terminal performance tool, powermetrics CLI, asitop alternative\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluidinference%2Ffluidtop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluidinference%2Ffluidtop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluidinference%2Ffluidtop/lists"}