{"id":49677578,"url":"https://github.com/srvr-farm/cpuwatch","last_synced_at":"2026-05-07T03:04:37.912Z","repository":{"id":356134306,"uuid":"1231190734","full_name":"srvr-farm/cpuwatch","owner":"srvr-farm","description":"Console UI for watching CPU stats","archived":false,"fork":false,"pushed_at":"2026-05-06T18:27:39.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-06T20:17:41.896Z","etag":null,"topics":["cpu-monitor","cpufreq","hardware-monitor","linux","lm-sensors","performance-monitoring","powercap","rapl","ratatui","rust","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srvr-farm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T18:08:56.000Z","updated_at":"2026-05-06T18:31:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/srvr-farm/cpuwatch","commit_stats":null,"previous_names":["srvr-farm/cpuwatch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/srvr-farm/cpuwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fcpuwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fcpuwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fcpuwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fcpuwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srvr-farm","download_url":"https://codeload.github.com/srvr-farm/cpuwatch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fcpuwatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32720778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["cpu-monitor","cpufreq","hardware-monitor","linux","lm-sensors","performance-monitoring","powercap","rapl","ratatui","rust","terminal","tui"],"created_at":"2026-05-07T03:04:32.542Z","updated_at":"2026-05-07T03:04:37.902Z","avatar_url":"https://github.com/srvr-farm.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cpuwatch - Linux CPU Monitor for the Terminal\n\n`cpuwatch` is a read-only Linux CPU monitor and terminal TUI for CPU clock\nspeed, per-core utilization, RAPL package power, configured power limits, and\ntemperatures. It is useful when you want a lightweight Rust alternative or\ncompanion to tools like `watch`, `sensors`, `htop`, `btop`, and `turbostat`.\n\nThe default mode is an interactive terminal UI. A `--once` mode is also\navailable for scripts, diagnostics, and non-interactive environments.\n\n## What You Can Monitor\n\nUse `cpuwatch` when you want to:\n\n- Monitor CPU frequency and clock speed on Linux from a terminal.\n- Watch per-physical-core CPU utilization instead of only per-thread CPU usage.\n- Inspect Intel RAPL or AMD RAPL package power draw in watts.\n- See Linux powercap limits, power level durations, and configured AMD\n  PPT/TDC/EDC values.\n- View CPU temperature readings from `lm-sensors` alongside clocks and power.\n- Debug laptop, desktop, workstation, homelab, and server CPU performance\n  without changing governors, power limits, or fan settings.\n\n## Features\n\n- Groups logical CPUs into physical cores using Linux CPU topology.\n- Shows current average, minimum, maximum, and delta CPU clocks.\n- Computes physical-core utilization from `/proc/stat` deltas.\n- Reads Linux powercap/RAPL domains and reports current watts when energy\n  counters are readable.\n- Displays RAPL power constraints such as long-term, short-term, and peak power\n  limits when the kernel exposes them.\n- Displays configured AMD power-limit values from `/etc/intel-plimit.conf` when\n  present.\n- Collects CPU and GPU-like temperature readings from `sensors`.\n- Degrades to `N/A` values and diagnostics when optional data sources are\n  missing or unreadable.\n\n## Keywords\n\nLinux CPU monitor, terminal CPU monitor, Rust TUI CPU monitor, CPU frequency\nmonitor, CPU clock speed monitor, per-core CPU usage, physical core utilization,\nLinux RAPL monitor, Intel RAPL, AMD RAPL, Linux powercap, CPU power monitor,\nCPU temperature monitor, `lm-sensors`, `cpufreq`, `/proc/stat`, `/sys` hardware\nmonitor.\n\n## Quick Start\n\nRun from the repository without installing:\n\n```sh\ncargo run -- --once\ncargo run -- --interval 500ms\n```\n\nBuild and install the release binary:\n\n```sh\nmake install\ncpuwatch --once\ncpuwatch\n```\n\nIf `/usr/local/bin` is not in your `PATH`, either add it or install with a custom\n`PREFIX`, `BINDIR`, or `INSTALL_PATH`.\n\n## Supported Systems\n\n`cpuwatch` targets Linux systems that expose CPU data through procfs and sysfs.\n\n| System type | Support level | Notes |\n| --- | --- | --- |\n| Linux on Intel x86/x86_64 with powercap/RAPL | Full | Expected to show topology, utilization, clocks, RAPL power, RAPL constraints, and temperatures when permissions and sensors are set up. |\n| Linux on AMD x86/x86_64 with powercap/RAPL | Full or partial | Recursive powercap discovery supports AMD RAPL layouts. Configured AMD PPT/TDC/EDC values can also be read from `/etc/intel-plimit.conf`. |\n| Linux systems without powercap/RAPL | Partial | CPU topology, clocks, utilization, and temperatures may work. Power sections show `N/A` or diagnostics. |\n| Linux VMs, containers, or restricted hosts | Partial | Virtualized or containerized environments often hide cpufreq, topology, sensors, or RAPL files. |\n| Non-x86 Linux | Partial | CPU topology/utilization may work if standard procfs/sysfs files exist. RAPL power data is usually unavailable. |\n| macOS, Windows, BSD, WSL without Linux hardware sysfs | Not supported for useful runtime data | The crate may compile on some non-Linux targets, but the monitor expects Linux `/proc` and `/sys` hardware interfaces. |\n\nThe TUI requires an interactive terminal. Use `--once` for CI, logs, scripts, or\nother non-interactive use.\n\n## Data Sources\n\n| Data | Source |\n| --- | --- |\n| CPU topology | `/sys/devices/system/cpu/cpu*/topology` |\n| CPU frequency | `/sys/devices/system/cpu/cpufreq/policy*/scaling_cur_freq`, with a fallback to per-CPU cpufreq paths |\n| CPU utilization | `/proc/stat` |\n| Power domains and energy counters | `/sys/devices/virtual/powercap` |\n| RAPL constraints | `constraint_*` files under powercap domains |\n| Configured AMD limits | `/etc/intel-plimit.conf` keys `AMD_PPT_W`, `AMD_TDC_A`, and `AMD_EDC_A` |\n| Temperatures | `sensors -j`, falling back to plain `sensors` output |\n\n`cpuwatch` does not write power limits, CPU governors, fan settings, or any other\nhardware controls.\n\n## Prerequisites\n\nRequired for building:\n\n- Rust 1.75 or newer.\n- Cargo.\n\nOptional but recommended:\n\n- `make`, for the repository build/install targets.\n- `sudo`, `setcap`, and `getcap`, for installing the binary with the file\n  capability used to read protected kernel files.\n- `lm-sensors`, for the `sensors` command and temperature readings.\n\nOn Debian or Ubuntu-style systems, the optional runtime tools are typically in:\n\n```sh\nsudo apt install make libcap2-bin lm-sensors\n```\n\nOn Fedora-style systems:\n\n```sh\nsudo dnf install make libcap lm_sensors\n```\n\nDistribution package names vary. If `setcap`, `getcap`, or `sensors` are not in\n`PATH`, install the package that provides them for your distribution.\n\n## Building\n\nBuild a debug binary:\n\n```sh\ncargo build\n```\n\nBuild an optimized release binary:\n\n```sh\ncargo build --release\n```\n\nThe release binary is written to:\n\n```sh\ntarget/release/cpuwatch\n```\n\nThe Makefile wraps the release build:\n\n```sh\nmake build\n```\n\n## Building Packages\n\nBuild Debian and RPM packages:\n\n```sh\nmake package VERSION=0.1.12\nmake check-packages VERSION=0.1.12\n```\n\nPackage artifacts are written to `dist/` by default:\n\n- `cpuwatch_0.1.12_amd64.deb`\n- `cpuwatch-0.1.12-1.x86_64.rpm`\n\nBoth packages install `cpuwatch` to `/usr/bin/cpuwatch`, keep the binary\nexecutable, and run this during package installation:\n\n```sh\nsetcap cap_dac_read_search+ep /usr/bin/cpuwatch\n```\n\nRequired package build tools:\n\n- `dpkg-deb`, usually provided by the Debian or Ubuntu `dpkg` package.\n- `rpmbuild`, usually provided by the Fedora, RHEL, or Debian `rpm` package.\n\n## Development Checks\n\nRun the full local check suite:\n\n```sh\nmake check\n```\n\nThat runs:\n\n```sh\ncargo fmt --check\ncargo test\ncargo clippy -- -D warnings\n```\n\nYou can also run individual targets:\n\n```sh\nmake fmt\nmake test\nmake clippy\n```\n\n## Installing\n\nThe recommended install path is through the Makefile:\n\n```sh\nmake install\n```\n\nBy default this:\n\n1. Builds `target/release/cpuwatch` if needed.\n2. Installs it to `/usr/local/bin/cpuwatch`.\n3. Applies the `cap_dac_read_search+ep` file capability.\n4. Prints the resulting capability with `getcap`.\n\nVerify the installed command:\n\n```sh\ncommand -v cpuwatch\ncpuwatch --once\n```\n\nIf you prefer to run the privileged install step explicitly, build first and\nthen run install under `sudo`:\n\n```sh\nmake build\nsudo make install\n```\n\nThe prebuild matters because `sudo make install` runs as root and the Makefile\nexpects the release binary to already exist in that case.\n\n### Custom Install Paths\n\nInstall under a different prefix:\n\n```sh\nPREFIX=\"$HOME/.local\" make install\n```\n\nInstall to a specific binary directory:\n\n```sh\nBINDIR=\"$HOME/.local/bin\" make install\n```\n\nInstall to an exact path:\n\n```sh\nINSTALL_PATH=\"$HOME/.local/bin/cpuwatch\" make install\n```\n\n### Installing Without Capabilities\n\nTo install only the binary:\n\n```sh\nmake install-binary\n```\n\nWithout the capability, `cpuwatch` still runs, but protected powercap files may\nbe unreadable and current watts may show as `N/A`.\n\nYou can apply or reapply the capability later:\n\n```sh\nmake capability\n```\n\nCheck the installed capability:\n\n```sh\nmake show-capability\ngetcap \"$(command -v cpuwatch)\"\n```\n\nRemove the installed binary:\n\n```sh\nmake uninstall\n```\n\n### Cargo Install\n\nYou can also install with Cargo:\n\n```sh\ncargo install --path .\n```\n\nCargo does not apply Linux file capabilities. If you need protected RAPL energy\ncounters, apply the capability to the installed binary manually or use\n`make install`.\n\n## Runtime Setup\n\n### Powercap and RAPL\n\nPower readings require Linux powercap/RAPL files under:\n\n```sh\n/sys/devices/virtual/powercap\n```\n\nCheck whether your system exposes domains:\n\n```sh\nls /sys/devices/virtual/powercap\n```\n\nCheck for energy counters:\n\n```sh\nfind /sys/devices/virtual/powercap -name energy_uj -print\n```\n\nIf domains exist but watts are `N/A`, the energy counters are probably\nunreadable by your user. Install with `make install`, run the installed binary,\nor run a one-off check with elevated privileges:\n\n```sh\nsudo target/release/cpuwatch --once\n```\n\nThe Makefile uses this default capability:\n\n```sh\ncap_dac_read_search+ep\n```\n\nSome filesystems or security policies may not preserve file capabilities. If a\nbinary is copied or replaced after install, run `make capability` again.\n\n### Temperatures\n\nTemperature readings use the `sensors` command from `lm-sensors`.\n\nVerify JSON output:\n\n```sh\nsensors -j\n```\n\nIf `sensors` is missing or returns no matching temperature labels, the\ntemperature panel will be empty or a diagnostic will be shown. On many Linux\nsystems, sensor detection and kernel driver setup are distribution-specific; use\nyour distro's `lm-sensors` setup documentation when readings are missing.\n\n### Configured AMD Limits\n\nIf `/etc/intel-plimit.conf` exists, `cpuwatch` reads these optional keys:\n\n```sh\nAMD_PPT_W=142\nAMD_TDC_A=95\nAMD_EDC_A=140\n```\n\nReadable non-empty values appear in the power panel as configured limits.\nMissing, unreadable, empty, or unparsable values are ignored.\n\n## Usage\n\nStart the interactive TUI:\n\n```sh\ncpuwatch\n```\n\nExit the TUI with any of:\n\n- `q`\n- `Esc`\n- `Ctrl-C`\n\nUse a custom update interval:\n\n```sh\ncpuwatch --interval 500ms\ncpuwatch --interval 2s\n```\n\nPrint one text report and exit:\n\n```sh\ncpuwatch --once\n```\n\nUse a custom sampling interval for the one-shot report:\n\n```sh\ncpuwatch --once --interval 250ms\n```\n\nIn `--once` mode, `cpuwatch` takes an initial sample, waits for the interval, then\ntakes a second sample so utilization and watts can be computed from deltas.\n\nShow CLI help:\n\n```sh\ncpuwatch --help\n```\n\nCurrent options:\n\n```text\nUsage: cpuwatch [OPTIONS]\n\nOptions:\n      --interval \u003cINTERVAL\u003e  [default: 1s]\n      --once\n  -h, --help                 Print help\n```\n\n## Troubleshooting\n\n- `no CPU topology found under /sys/devices/system/cpu`: the process cannot see\n  the Linux CPU sysfs tree. This commonly happens on unsupported OSes,\n  restricted containers, or unusual minimal environments.\n- `no RAPL/powercap domains found`: the kernel did not expose powercap domains\n  to this environment. Power readings are unavailable, but CPU\n  clocks/utilization and temperatures may still work.\n- `RAPL energy counters are unreadable`: power domains were found, but\n  `energy_uj` files could not be read. Install with `make install`, reapply\n  `make capability`, or run as a user with permission to read those files.\n- No temperatures appear: install and configure `lm-sensors`, then verify that\n  `sensors -j` returns CPU or GPU-like temperature readings.\n- CPU clocks show `N/A`: the system may not expose cpufreq files, or the process\n  may be running in a VM/container where host CPU frequency is hidden.\n- The TUI does not render correctly: use a real interactive terminal with enough\n  width and height, or use `cpuwatch --once` for plain text output.\n\n## Repository Layout\n\n- `src/main.rs`: binary entry point.\n- `src/lib.rs`: mode selection, TUI loop, and terminal lifecycle.\n- `src/cli.rs`: command-line options.\n- `src/cpu.rs`: topology, frequency, and utilization readers.\n- `src/power.rs`: powercap/RAPL discovery, constraints, and watt calculations.\n- `src/sensors.rs`: `sensors` collection and parsing.\n- `src/snapshot.rs`: combined sampling state.\n- `src/render.rs`: TUI rendering and one-shot text reports.\n- `Makefile`: build, install, capability, and check targets.\n\n## Suggested GitHub Topics\n\nFor the repository About sidebar, useful topics would be:\n\n```text\nlinux\nrust\ntui\nterminal\ncpu-monitor\nhardware-monitor\nperformance-monitoring\nrapl\npowercap\nlm-sensors\ncpufreq\nratatui\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrvr-farm%2Fcpuwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrvr-farm%2Fcpuwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrvr-farm%2Fcpuwatch/lists"}