s-tui: CPU Stress and Thermal Monitoring in the Terminal

The question s-tui answers: why is this CPU slow right now

Most system monitors tell you that a CPU is busy. s-tui is built around a narrower question: is the chip being held back, and by what. The README lists its scope as monitoring CPU temperature, utilization, frequency and power, and showing "performance dips caused by thermal throttling". That framing matters. A utilization graph alone cannot distinguish a chip running at full speed from one pinned at its base clock because a power or thermal limit is in force.

The audience follows from that. If you run a workload on a laptop, a small server or a single-board computer and you suspect the cooling or the power delivery is the bottleneck, s-tui puts the relevant readings on one screen. It requires no X server, so it works over SSH. It is also Linux-specific: setup.py declares the classifier "Operating System :: POSIX :: Linux", and the installation methods in the README are all Linux package managers or pip. Anyone on macOS or Windows is outside the supported set.

How the TUI is laid out and what the side bar controls

The interface is a text UI built on urwid, which setup.py lists as a dependency alongside psutil. The README describes the layout: graphs on the main area, a side bar of controls, and sensor readings in text form at the bottom. Navigation is by arrow keys or hjkl. The Modes section holds radio buttons that toggle between stressed and regular operation, and the Stress options section lets you change the stress defaults. Graphs and Summaries menus select which plots and which text summaries appear. A Reset button clears graphs and statistics, a UTF-8 button switches to a smoother graph rendering when the system supports it, and Save Settings persists the current configuration.

Because the graph and the summary text are driven by the same sensors, the throttle indicator shows up in two places at once: the frequency graph changes color and the summary text changes color, with a reason label appended. That coupling is the useful part. You do not have to watch a number cross a line; the display changes state when throttling is detected.

Throttle reason labels depend on root and the msr module

This is the most distinctive feature and also the one with the most caveats. The README splits the labels by platform and by privilege level.

On Intel, with root and the msr module loaded, s-tui reads IA32_THERM_STATUS and reports per-core reasons: T for thermal (core temperature exceeded TjMax), H for PROCHOT (an external thermal signal from the VRM, GPU or battery), C for critical (near emergency shutdown temperature), W for power limit (PL1/PL2 watt budget exceeded), A for current limit, and X for cross-domain throttling. Labels can combine with a slash, so T/W means both a thermal and a power cause.

On AMD, with root and msr, the only label is Pc, a P-state cap read from PStateCurLim. The README is explicit that AMD exposes no equivalent of Intel's reason breakdown through MSRs, because the thermal, power and current limits (PPT, TDC, EDC, THM, STAPM) live in the SMU power-management table and need an out-of-tree kernel module to reach. So Pc tells you a cap is in force, not why. The README also calls it a severity threshold rather than a reason code, and notes that on a well-cooled part that is boost-limited but never pushed below its rated base clock, Pc is expected to stay clear.

Without root, s-tui falls back to sysfs and reports thermal throttling only, as Tc for a core throttle or Tp for a package throttle that affects all cores. If you run s-tui as an ordinary user and see no throttle labels, that is the fallback, not evidence that nothing is throttling.

Installing s-tui and running a first stress test

The README calls pip the most up to date source. A user install places an executable in ~/.local/bin, which the README warns must be on your PATH.

pip install s-tui --user

Distributions package it too, and the commands differ per release. On Ubuntu 18.10 and newer, Debian 10 and newer, and Fedora, the README gives:

sudo apt install s-tui

sudo dnf install s-tui

On Arch Linux and Manjaro it is in the Arch repository, so pacman installs it directly, and an s-tui-git package follows the master branch.

sudo pacman -S s-tui

Once installed, running the binary with no arguments opens the TUI.

s-tui

From there the README's workflow is: use the arrow keys or hjkl to move around the side bar, switch the Modes radio buttons from regular to stressed operation, adjust load parameters under Stress options, choose what to plot under Graphs, and press q or the Quit button to exit. If you want the numbers without the interface, the CLI options cover that. The -t flag prints a single line of stats, -j prints a single line as JSON, and -c writes stats to a CSV file whose name defaults to s-tui_log_<TIME>.csv. For a quick check that the tool works, -dr runs for five seconds and quits. The temperature threshold that triggers the color change defaults to 80 degrees and is set with -tt.

The built-in stress test and when it is the wrong load

s-tui ships with a stress test that the README says has zero dependencies and works out of the box, with optional integration with external tools such as stress and stress-ng. The extras_require block in setup.py confirms this shape: installing the stress extra pulls in numpy, and the README says numpy is what gives better stress performance. So the default load generator is pure Python, and numpy is an optional accelerator.

That design has a consequence worth stating plainly. A pure Python load generator is convenient and portable, but it is not the same load as a compiled stress-ng run with a chosen method and a chosen number of workers. If your goal is to validate a cooling solution against a reproducible, method-specific workload, s-tui's built-in test is the wrong instrument. Use it to put the CPU under sustained load while you watch the graphs, and reach for stress-ng when the load itself has to be specified precisely. The README treats the external tools as an option rather than the default, which is a reasonable choice for a tool whose main job is the display.

s-tui compared with btop and with stress-ng

The two comparisons people reach for are btop and stress-ng, and they are different kinds of tools.

btop is a general system monitor. It shows processes, memory, disks, network and per-core utilization in a terminal. s-tui does not do per-process accounting or disk and network statistics; its sensor set is CPU temperature, frequency, power and utilization, plus throttle reason labels. If you want to know which process is eating the machine, btop is the right tool and s-tui will not help. If you want to know whether the CPU is being capped by a thermal or power limit, s-tui carries information btop does not, particularly the Intel reason codes and the AMD P-state cap.

stress-ng is a load generator, not a monitor. It offers many stress methods and precise control over workers and duration. s-tui's built-in stress mode is the opposite trade: less control, no dependencies, one screen where the load and the resulting thermal behavior sit together. The honest reading is that s-tui is a monitor that can generate load, and stress-ng is a load generator that expects you to bring your own monitoring. Running stress-ng while watching s-tui is the combination the README itself points at.

Licence, packaging and the cost of keeping it current

s-tui is GPL-2.0. The LICENSE file is at the repository root, setup.py declares license="GPLv2" and the classifier "GNU General Public License v2 (GPLv2)", and the source headers carry the standard GPLv2 notice. If you redistribute s-tui, or ship a product that bundles it, the GPLv2 terms apply to that distribution. That is a description of the licence, not legal advice; check with your own counsel before bundling it into a closed product.

Upgrade cost looks low. There are three releases in the recent window: v1.3.0 on 2026-01-12, v1.4.0 on 2026-03-19 and v1.5.0 on 2026-08-19. The dependency floor is modest, urwid>=3.0.2 and psutil>=7.0.0, so the practical upgrade risk is the same as any Python tool that reads system sensors: kernel and psutil changes can alter what is readable. The repository also carries a Makefile with test targets, including a mocked suite that needs no hardware and a separate hardware-marked suite. If you are packaging s-tui yourself, those targets are the fastest way to check whether a new release still behaves on your distribution.

The last push to the repository was on 2026-09-15, so the project is not dormant. It is also not a large surface: the package is s_tui plus s_tui.sources and s_tui.sturwid, and the entry point is s-tui=s_tui.s_tui:main.

Editorial conclusion

Adopt s-tui if you are on Linux and your question is whether a CPU is throttling, and you want the answer in a terminal over SSH without an X server. Skip it if you need per-process accounting, GPU monitoring, or a cross-platform tool; s-tui is POSIX Linux only and its stress mode is a load generator, not a validated benchmark. Before relying on the throttle labels, verify that the msr kernel module is loaded and that you are running as root, because without it s-tui falls back to sysfs and reports only Tc and Tp.

Frequently asked questions

Official sources

1. amanusk/s-tui on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases