A fast, truthful terminal dashboard for AMD GPUs on Linux.
GPUFlo answers three questions within one second:
- What is the selected physical GPU doing?
- How much of its applicable memory pool is occupied?
- Is a source-backed fault, throttle, limit, pressure, sleep, permission, or telemetry problem active?
It is strictly local and read-only. GPUFlo reads Linux amdgpu kernel interfaces directly, never changes GPU state, never contacts a remote service, and never requires an inference engine integration. Busy activity and full memory are treated as useful work—not as errors.
- Responsive Ratatui dashboard with full, compact, mini, and one-line views.
- Live GPU activity and memory graphs with 60 seconds of bounded history and session peaks.
- Physical-GPU and XCP-aware topology without fabricated node-wide utilization.
- Socket-scoped temperature and power kept separate from partition-scoped activity, memory, and clocks.
- Factual health reporting for source-backed faults, throttles, limits, memory pressure, stale data, sleep, permission failures, and telemetry failures.
- Honest unavailable states instead of zeroes, blank values, or guessed data.
- Process attribution overlay for PID, name, GPU/XCP, VRAM, GTT, KFD memory, and container identity.
- Human, JSON, and NDJSON output from the same canonical telemetry model.
- Four themes and complete no-color operation without making color carry required meaning.
- 100 positive rotating taglines—one is chosen randomly at launch and remains stable for that session.
- Optional sleeping ASCII cat (
--cat)—naps in the margin once the selected GPU is warm; pure decoration, never touches telemetry. - Optional runtime AMD SMI enrichment without a build-time or startup dependency.
- Small daily summaries containing peaks, energy when available, and throttle episodes; raw samples are never persisted.
- Reusable Rust library API exposing the canonical model and bounded
Monitorinterface. - Terminal-safe lifecycle with cursor, raw-mode, and alternate-screen restoration on normal quit, catchable signals, and fatal errors.
The runtime requirements are deliberately small:
- Linux;
- at least one AMD PCI/DRM device bound to the in-kernel
amdgpudriver.
GPUFlo does not require:
- ROCm userspace;
- the
amd-smiexecutable; - the AMD SMI library;
/dev/kfd;- root;
- membership in the
renderorvideogroups; - a daemon, database, network connection, or cloud account.
Optional sources add information when available. Their absence never prevents kernel-backed monitoring from starting.
cargo install gpuflo --lockedcurl -fsSL https://raw.githubusercontent.com/mikeroySoft/gpuflo/main/install.sh | shThe script downloads the latest x86_64-unknown-linux-gnu release archive
from GitHub, verifies its SHA-256 checksum, and installs the single binary
into ~/.local/bin (override with GPUFLO_INSTALL_DIR). It never uses root
and never modifies groups, udev rules, services, or GPU settings.
The same archives can be downloaded and verified manually from the
releases page; each release
ships SHA256SUMS, a GLIBC baseline report, and its validation manifest.
Rust 1.96 or newer is required.
git clone https://github.com/mikeroySoft/gpuflo.git
cd gpuflo
cargo install --path . --lockedThe binary is installed as ~/.cargo/bin/gpuflo by default.
To build without installing:
cargo build --release --locked
./target/release/gpufloThe release workflow produces a qualified x86_64-unknown-linux-gnu archive containing exactly:
gpuflo
LICENSE
THIRD_PARTY_NOTICES.txt
README.md
Published archives are accompanied by SHA256SUMS and a validation manifest. Source publication supports the same package as a binary and as a Rust library; release notes state which hardware regimes were live-qualified, fixture-validated, or unverified.
cargo uninstall gpufloOptional user-owned files may be removed separately:
~/.config/gpuflo/config.toml
~/.local/state/gpuflo/daily.json
Installation and removal never modify groups, udev rules, services, drivers, or GPU settings.
Start GPUFlo with no output-mode flag:
gpufloThe dashboard continuously samples telemetry while rendering animation independently. Arrow keys change the selected physical GPU without conflating display position with stable identity.
| View | Minimum terminal area | Contents |
|---|---|---|
mode |
72×34 |
GPUFlo logo, random session tagline, GPU strip, activity and memory graphs, support telemetry, active health, and key hints |
compact |
62×17 |
Header, GPU strip, graphs, support telemetry, and active health without the logo block |
mini |
48×11 |
Activity and memory graphs |
tiny |
any size | One interactive selected-GPU status line |
auto chooses the richest view that fits. A forced preference still falls back safely when the terminal is too small; it never grants permission to clip content.
Launch a particular interactive view:
gpuflo --mode compact
gpuflo --mode mini
gpuflo --mode tiny--mode tiny is the persistent interactive view. The separate --tiny flag prints one line and exits.
| Key | Action |
|---|---|
← / → |
Select the previous or next physical GPU (h also selects previous) |
l |
Toggle the logo and recenter the layout for this session |
t |
Cycle Buffalo, Nord, and monochrome themes for this session |
m |
Cycle the preferred responsive view for this session |
p |
Toggle the process-attribution overlay |
d |
Toggle the selected-GPU detail overlay |
? |
Toggle help and current presentation state |
q / Esc |
Quit and restore the terminal |
Theme and view changes are session-only. GPUFlo never rewrites the user's configuration file.
- stable opaque GPU identity;
- display index;
- PCI BDF;
- model name;
- source UUID and serial when exposed;
- physical GPU to XCP partition hierarchy;
- primary-partition ownership of socket-scoped telemetry.
- GFX activity percentage;
- applicable memory pool: VRAM, shared memory, or GTT;
- memory used, total, and occupancy percentage;
- hotspot temperature and source-reported limit;
- socket power and source-reported cap;
- GFX clock;
- optional memory-controller activity;
- fixed-capacity activity and occupancy histories;
- session activity peak;
- highest-priority active source-backed health condition.
The detail overlay exposes the selected GPU's identity, topology, health, activity, memory pool and capacities, occupancy, clocks, temperature, power, and exact unavailable reasons.
Physical GPUs own socket-wide temperature, power, identity, and health. XCP partitions own activity, memory, GFX clock, and memory-controller activity. GPUFlo does not average unrelated devices, synthesize a physical-GPU utilization percentage from partitions, or duplicate socket observations across XCPs.
Press p to open the process overlay. It can show:
| Field | Meaning |
|---|---|
| PID | Linux process ID |
| name | Process name when permitted |
| GPU/XCP | Attributed physical GPU and partition |
| VRAM | Resident DRM fdinfo VRAM accounting |
| GTT | Resident DRM fdinfo system/GTT accounting |
| KFD | Separately sourced KFD VRAM accounting |
| container | Container identity inferred from process cgroups when available |
Important semantics:
- DRM fdinfo and KFD memory are independent accounting systems; GPUFlo does not add or reconcile them.
- The validated Linux interfaces expose process association and memory, but not a truthful per-process HIP utilization share. GPUFlo therefore does not display one.
- Other users' process details may require permissions. Affected fields remain visible as
permission deniedrather than silently disappearing. - Process scanning runs on an isolated two-second lane and only while the overlay is open, so it cannot block the 250 ms kernel lane.
GPUFlo treats high activity and high memory occupancy as neutral. Health changes only when a telemetry source reports a condition or required telemetry becomes unavailable.
Active conditions are prioritized as:
- fault or severe RAS condition;
- thermal, power, current, or other source-reported throttle;
- source-reported limit;
- unavailable, stale, permission-limited, asleep, or failed telemetry;
- source-reported memory pressure.
When no condition is active, the main health row remains empty rather than printing a generic reassurance.
Every metric is either a value with its source observation time or exactly one explicit state:
| State | Meaning |
|---|---|
unsupported_hardware |
Structurally inapplicable or explicitly unsupported by the source |
unsupported_driver_version |
A known ABI, driver, or gpu_metrics layout cannot be interpreted safely |
permission_denied |
The active source exists but cannot be read by this user |
asleep |
Runtime-suspended amdgpu denied the read; GPUFlo does not wake it |
reported_by_primary_partition |
The value belongs to the primary XCP or physical-GPU scope |
stale |
The last good observation exceeded its freshness deadline |
source_error |
A recognized source failed, timed out, or returned malformed data |
Missing, stale, malformed, unsupported, and denied telemetry never becomes numeric zero. A transient failed read retains the last value only while it remains fresh; retained and stale data never enter histories, peaks, rates, or daily summaries.
The kernel path is authoritative:
- DRM and PCI sysfs discovery;
- textual
amdgpusysfs nodes; - hwmon temperature and power nodes;
- versioned binary
gpu_metricspayloads; - RAS, throttle, and source-reported health information when implemented by the device;
- DRM fdinfo and optional KFD process evidence.
Implemented gpu_metrics families are v1.3–v1.8, v2.1–v2.4, and v3.0. Dynamic v1.9 is detected and represented as unsupported_driver_version rather than decoded with a guessed structure; independent stable text nodes continue reporting.
Discrete-GPU gpu_metrics v1.3 firmware on RDNA 3 and RDNA 4 keeps the TEMP_HOTSPOT throttle bit set even at idle (drm/amd#3251, ROCm/rocm-systems#11781). GPUFlo ignores that one bit, as MangoHud does; power, current, and other temperature throttle bits still report.
When libamd_smi.so is available, GPUFlo loads it at runtime and uses it only to enrich fields not supplied by a fresh kernel observation. A missing library, incompatible ABI, unavailable symbol, or runtime failure disables only enrichment and is retried behind a cooldown.
Run gpuflo --help for the authoritative option reference.
| Flag | Behavior |
|---|---|
--once |
Print one human-readable line per physical GPU, then exit |
--json |
Print one pretty schema-version-1 JSON snapshot containing every physical GPU, then exit |
--json-stream |
Continuously print compact NDJSON snapshots at the production cadence |
--for <duration> |
Stop --json-stream after a window; positive seconds (bare or s), minutes (m), or hours (h), including decimals |
--tiny |
Print one selected-GPU status line, then exit |
--gpu <index|id|bdf> |
Select the GPU for --tiny or the initial interactive selection |
--theme <buffalo|nord|monochrome|terminal> |
Select the interactive theme |
--mode <auto|mode|compact|mini|tiny> |
Select the preferred interactive view |
--no-color |
Disable interactive color |
--cat |
Show a sleeping ASCII cat once the selected GPU is warm |
Examples:
# Human summary for every GPU
gpuflo --once
# One machine-readable snapshot
gpuflo --json
# Continuous records; broken pipe is a successful exit
gpuflo --json-stream | head -n 10
# Capture a bounded stream without a supervisor
gpuflo --json-stream --for 2.5m > capture.ndjson
# One selected GPU by PCI address
gpuflo --tiny --gpu 0000:03:00.0
# Start the TUI on display index 1
gpuflo --gpu 1--once, --json, and --json-stream always report all physical GPUs; --gpu does not filter those all-GPU surfaces.
Human and machine output is always ANSI-free. Exit codes are:
| Code | Meaning |
|---|---|
0 |
Success, partial telemetry, or downstream broken pipe |
1 |
Fatal runtime failure, no startup GPU, or output failure |
2 |
Invalid CLI usage or configuration |
130 |
Interrupted by SIGINT |
JSON and NDJSON use the same nested physical-GPU/XCP model as the TUI. The envelope contains:
- integer
schema_version; - producing
gpuflo_version; - RFC 3339 UTC
sampled_attime; - optional run-local
sequencefor streamed records; - every physical GPU and its nested partitions.
Every physical GPU carries gpus[].platform in both --json and every
--json-stream snapshot, for example:
"platform": {"id": "strix_halo", "memory_pool": "gtt"}This is discovery classification of the physical GPU, not an XCP partition property or a stream-envelope field. Both writers serialize the same classification.
platform.id |
platform.memory_pool |
Discovery evidence |
|---|---|---|
strix_halo |
gtt |
Recognized AMD PCI device 1002:1586; takes precedence over conflicting heap evidence |
generic_apu |
gtt |
Unrecognized device with KFD unified-memory heap evidence |
generic_discrete |
vram |
Unrecognized device with KFD dedicated-memory heap evidence |
unknown |
unknown |
Neither device recognition nor conclusive heap evidence |
memory_pool identifies the applicable accounting pool: gtt is GTT-backed
unified memory, vram is dedicated video memory, and unknown means the evidence
does not establish the pool. A large GTT allocation or aperture on a discrete GPU
does not change its classification. Measured usage, totals, and unavailable
states remain in gpus[].partitions[].memory; identity alone does not establish
capacity, workload suitability, or NPU capability.
The field is additive within schema version 1. Consumers should tolerate new
fields and new string values. Deserializing a legacy snapshot without platform
into GPUFlo's public model defaults it to
{"id":"unknown","memory_pool":"unknown"}; serialization includes that default.
Unrecognized future platform-ID and memory-pool strings survive deserialization
and serialization unchanged, rather than being replaced with unknown.
The explicit unknown classification means inconclusive evidence, not an error
or an assertion that the device has no usable memory.
A current observation has a value and source time:
{
"value": 97.0,
"observed_at": "2026-08-21T23:45:12.247Z"
}An unavailable observation has its exact state:
{
"state": "permission_denied"
}A stale observation preserves the last good source time but contains no numeric value:
{
"state": "stale",
"observed_at": "2026-08-21T23:45:08.000Z"
}GPUFlo never emits JSON null, NaN, infinity, a stale numeric value, or an unavailable numeric zero. NDJSON records are independently valid objects. Sequence gaps can reveal that a slow consumer missed superseded snapshots; collection remains bounded instead of accumulating an unbounded queue.
schema_version is the machine-output compatibility key and is currently 1.
Pin on it; the invariants above are part of the contract a major version
protects, not incidental behavior.
Within a major version GPUFlo may add envelope, physical-GPU, and partition
fields, and may emit state strings beyond the seven documented states.
Consumers must ignore unknown object keys and must treat an unrecognized state
as "unavailable, reason unknown" rather than as an error—GPUFlo's own model
round-trips an unknown state string unchanged instead of collapsing it into a
known value, and consumers are expected to do the same.
schema_version increments only when an existing field is removed, renamed,
retyped, or has its meaning changed.
gpuflo_version is the semver of the producing binary and is not a payload
compatibility key. A newer gpuflo_version reporting the same schema_version
makes no breaking payload change; consumers pin on schema_version instead.
The optional configuration file is:
$XDG_CONFIG_HOME/gpuflo/config.toml
with fallback:
~/.config/gpuflo/config.toml
The complete schema is intentionally small:
theme = "buffalo" # buffalo | nord | monochrome | terminal
mode = "auto" # auto | mode | compact | mini | tiny
no_color = false
cat = false # sleeping ASCII cat when the selected GPU is warmSet theme = "terminal" to use the terminal's foreground, background, and ANSI palette. On Omarchy 4, theme switches retint open terminals, so a running GPUFlo follows the active Omarchy theme without extra hooks.
Precedence is:
built-in defaults → TOML → CLI
Any non-empty NO_COLOR environment variable disables color unconditionally. Unknown keys, invalid values, wrong types, and malformed TOML fail before terminal takeover with exit code 2; typos are never silently ignored.
GPUFlo stores one small optional daily summary at:
$XDG_STATE_HOME/gpuflo/daily.json
with fallback:
~/.local/state/gpuflo/daily.json
It contains per-GPU activity and memory peaks, energy when a source provides a usable counter, and throttle episodes from the kernel health signal GPUFlo already reads. The throttle_episodes key is omitted for a GPU with none. Each episode records started_at (the local-offset RFC 3339 time of the first observation with an active source-reported throttle), ended_at (when first observed to have ended), duration_seconds, and reasons (the source-named reason groups as first observed). An in-progress throttle episode is saved open, without ended_at or duration_seconds. Up to 64 throttle episodes are kept per GPU per day; closed episodes are dropped oldest-first across GPUs to stay within the 64 KiB file budget, but an open episode is never dropped. Throttle episodes appear only in daily.json, not in the TUI or --json/--json-stream output. No new source, process, name, or command-line data is stored.
Writes are atomic. Raw samples, graphs, process rows, names, container identities, and command lines are never persisted.
GPUFlo performs no network access and has no telemetry upload, update check, remote API, service, or daemon.
The persistent interactive mini view works well as a floating terminal dashboard:
alacritty \
--class gpuflo,gpuflo \
--title "GPUFlo Mini" \
-o 'window.dimensions.columns=74' \
-o 'window.dimensions.lines=15' \
-e gpuflo --mode miniFor Niri, match the dedicated Wayland app ID:
window-rule {
match app-id="gpuflo"
open-floating true
open-focused false
default-floating-position x=24 y=24 relative-to="bottom-right"
}The same launch command can be placed behind a compositor keybinding or startup rule. compact provides more telemetry at 62×17 or larger; tiny supplies a persistent one-line widget.
With gpuflo and jq on PATH, add this rule to ~/.config/hypr/apps.lua
(or another loaded Hyprland Lua window-rules file):
o.window("org.omarchy.gpuflo", { tag = "+floating-window" })Check omarchy menu keybindings --print before choosing a free key. For
example, if SUPER + ALT + P is free, add to ~/.config/hypr/bindings.lua:
o.bind("SUPER + ALT + P", "GPUFlo", "omarchy-launch-or-focus-tui --app-id=org.omarchy.gpuflo gpuflo --mode compact")For an app-launcher entry, run:
omarchy-tui-install GPUFlo "gpuflo --mode compact" float utilities-system-monitorThe launcher uses the shared TUI.float app ID; the dedicated keybinding
above uses org.omarchy.gpuflo for focus-or-launch.
Optionally add an entry inside ~/.config/omarchy/extensions/omarchy-menu.jsonc:
For the Quattro bar, copy scripts/omarchy-bar to an executable path such as
~/.local/bin/gpuflo-omarchy-bar. Add this item to a bar.layout section
(for example right) in ~/.config/omarchy/shell.json:
{"id":"gpuflo","type":"command","exec":"~/.local/bin/gpuflo-omarchy-bar","interval":5,"onClick":"omarchy-launch-or-focus-tui --app-id=org.omarchy.gpuflo gpuflo --mode compact"}Use an interval of at least 1 second. The wrapper returns one JSON line with
text, tooltip, and class; class is "active" only for a throttle or
fault. It reads primary-partition activity and physical-GPU hotspot, socket
power, and health from schema version 1. Its isolated
XDG_STATE_HOME="$XDG_RUNTIME_DIR/gpuflo-bar" is required so bar polls do not
rewrite your real daily.json.
Multiple GPUFlo processes can run at once. They do not claim exclusive GPU access, ports, sockets, or singleton locks. Each instance owns its selection, tagline, graphs, session peaks, overlays, and sampling lanes.
One caveat: CLI instances normally share the daily summary file. Writes remain atomic, but concurrently exiting processes can replace one another's independently accumulated peaks and throttle episodes. Isolate an occasional secondary instance with a session-local state root:
XDG_STATE_HOME="$XDG_RUNTIME_DIR/gpuflo-terminal" gpufloThe normal configuration file remains shared because GPUFlo never writes it.
- New and returning GPUs are rediscovered and probed from scratch.
- A confirmed disconnected GPU is removed from subsequent snapshots without suppressing healthy devices.
- Selection moves to a surviving GPU and can return to the remembered stable identity when the device reappears.
- A running TUI or JSON stream can remain alive with zero currently detected GPUs and continue discovery.
- A confirmed XCP partition-configuration change stops output and requests a restart rather than joining incompatible old and new identities.
- Potentially blocking kernel, AMD SMI, process, discovery, and persistence work runs on bounded isolated lanes.
- Missed ticks are skipped, never replayed or queued indefinitely.
The package also exposes a narrow semver-supported Rust interface:
- canonical IDs, topology, observations, health, memory, power, temperature, timestamps, and snapshots;
MonitorandMonitorOptions;- owned
MonitorEvent::Snapshot,Notice, andFatalevents; - bounded receive, command, process-scope, peak-reset, and shutdown operations.
This interface is versioned by the package's semver; the machine-output payload
is versioned separately by schema_version.
The model structs are #[non_exhaustive]: obtain them from Monitor events
or by deserializing GPUFlo JSON, then read their public fields. New fields may
arrive in minor releases.
Minimal use:
use gpuflo::{Monitor, MonitorEvent, MonitorOptions};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let monitor = Monitor::start(MonitorOptions::new())?;
loop {
match monitor.receive()? {
MonitorEvent::Snapshot(snapshot) => {
println!("observed {} physical GPU(s)", snapshot.gpus.len());
break;
}
MonitorEvent::Notice(notice) => eprintln!("{}", notice.message),
MonitorEvent::Fatal(error) => return Err(error.into()),
_ => {}
}
}
monitor.shutdown()?;
Ok(())
}MonitorOptions::new() disables daily persistence for embedders. Source adapters, reducers, histories, rendering state, terminal lifecycle, and unsafe AMD SMI handles remain private implementation details.
GPUFlo does not:
- tune clocks, power, fans, partitions, or voltage;
- reset or mutate a GPU;
- infer LLM phases or report tokens per second;
- connect to inference-engine APIs;
- invent per-process GPU utilization;
- average unlike GPUs into a node-wide utilization percentage;
- hide missing telemetry behind zero or
N/A; - collect remote hosts or fleet telemetry;
- run a daemon, service, database, or web server;
- require root or recommend running the dashboard as root.
cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo build --release --locked
cargo package --lockedValidation is deliberately risk-based rather than exhaustive. It covers source fixtures, observation semantics, physical/XCP scope, bounded monitor journeys, text and JSON contracts, responsive rendering, actual PTY terminal restoration, packaging, and live hardware evidence. See validation/ for the current manifest and exact qualification claims.
Maintainers can follow the release checklist for the validation, tagging, and publication steps.
GPUFlo is licensed under the MIT License. Locked dependency and reused-code notices are included in THIRD_PARTY_NOTICES.txt.
