8000 GitHub - arinal/toph: TUI that ranks top CPU-hogging processes over a growing window and lets you kill them · GitHub
[go: up one dir, main page]

Skip to content
arinalPublic

About

TUI that ranks top CPU-hogging processes over a growing window and lets you kill them

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

14 Commits

Folders and files

Repository files navigation

toph

toph - top hog. An anagram of htop, named after the blind earthbender who senses what's hidden through vibrations, then strikes with precision. First you examine the CPU hog; then you deal with it.

An interactive TUI that ranks the most CPU- (or memory-) hungry processes over a growing window, groups multi-process apps into one row, and lets you kill them gracefully or forcefully.

toph in action

Unlike htop (which shows instantaneous CPU usage, causing the list to jitter constantly) or ps --sort=-%cpu (which reports the lifetime average since each process started), toph averages CPU usage over the wall-clock time since you launched it. The ranking gets more stable the longer you watch.

Why

Built to scratch a specific itch: "something is eating my CPU right now, which process is it, and let me kill it without having to play whack-a-mole with a constantly-reordering top window."

  • Growing window: the average stabilizes as more time passes — you can act as soon as you trust the ranking.
  • App grouping: Chrome's 40 renderers or an Electron app's helper swarm collapse into a single row with summed CPU/RAM, so you see the app, not the process soup. One kill takes the whole group down.
  • Recognizable rows: processes are classified into runtime families (Chrome, Firefox, Electron, Java, Python, Node, shells, kernel threads) and known apps, each shown with an icon and a friendly label like Chrome — renderer instead of a raw command line.
  • Confirmed kill: no accidental SIGKILLs from a fat-finger.
  • Non-blocking UI: sampling runs on a separate task; key input never lags while the process table is being read.

Install / Run

From crates.io

cargo install tophog      # the crate is `tophog`; it installs a `toph` command

From source

cargo install --git https://github.com/arinal/toph    # latest from main
# or, from a local checkout:
cargo install --path .                                # drops `toph` in ~/.cargo/bin
cargo run --release                                   # run without installing

The interactive TUI requires a real TTY (raw mode), so it won't work piped or with redirected stdin.

Icons

toph ships two glyph sets: emoji (renders in most modern terminals) and Nerd Font (sharper, monospace-aligned, needs a Nerd Font installed). The interactive TUI auto-detects which to use by probing the terminal, and falls back to emoji when the result is inconclusive.

Override the detection explicitly, in order of precedence:

toph --nerd-font            # force Nerd Font glyphs
toph --nerd-font=false      # force emoji
TOPH_NERD_FONT=1 toph       # env var (1/true/on or 0/false/off)

To make a choice persistent, export the env var from your shell rc file:

# ~/.zshrc (or ~/.bashrc)
export TOPH_NERD_FONT=1     # always use Nerd Font glyphs

Detection is best-effort — if your icons look like boxes (tofu), pass --nerd-font=false; if you have a Nerd Font but get emoji, pass --nerd-font. Snapshot mode (--once) can't probe, so it defaults to emoji unless told otherwise.

Snapshot mode (non-interactive)

For scripts, CI, or piping - sample for a few seconds and print a plain table:

toph --once               # 3s window, default rows
toph --once --secs 5      # 5s window
toph --once --top 50      # 50 rows

No TTY needed; output goes to stdout. Rows that appeared after the window started are marked with a leading *.

Keybinds

Key Action
j / k or ↓ / ↑ Move selection (vim-style or arrows)
s Toggle sort: CPU ⇄ RAM
v Cycle view size: 25 → 50 → 100 → 25…
g Toggle app grouping (on by default). Grouped: Chromium browsers, Firefox, and Electron apps collapse to one row per app, CPU/RAM summed. Ungrouped: one row per process (per-tab / per-renderer).
y Copy the selected row's executable path to the clipboard (OSC 52)
d Send SIGTERM (graceful) to the selection - confirms with y/n
D Send SIGKILL (force) to the selection - confirms with y/n
r Reset the averaging window - re-baselines all processes
q / Esc / Ctrl-C Quit

Killing a grouped row signals every process in the group. Copy uses OSC 52, so the yanked path lands on your real clipboard even over SSH.

How the averaging works

Every second, the sampler refreshes the process table (via the sysinfo crate) and records each process's total accumulated CPU time and current resident memory.

CPU% derived from a cumulative counter, so we diff over the window:

cpu% = (cpu_ms_now - cpu_ms_at_baseline)
   
6C3A
  / (wall_ms_now - wall_ms_at_baseline)
     / num_cores
     * 100

RAM avg — memory is a gauge, not a counter, so we accumulate samples and report the arithmetic mean of observed RSS over the window:

ram_avg = sum(rss_samples) / sample_count

The CPU baseline and memory accumulator are captured the first time a process is observed (typically at launch). Pressing r re-baselines and resets the memory accumulator for every process. A process that exits is dropped from the table; a process that starts mid-run is inserted with fresh state. A row needs at least half a second of window before its CPU% is considered meaningful, so brand-new processes briefly sit out of the ranking.

Architecture

The code is structured as a small "onion": a pure core (domain state and logic) surrounded by side-effecting adapters (terminal, signals, sampling), wired together in main.rs. The boundaries are expressed as traits (ports) so the core can be tested against fakes.

Module Role
main.rs Terminal setup, tokio runtime, the select! event loop, CLI args
app.rs App state, ranking, grouping, Action → state transitions
sampler.rs Refreshes sysinfo, classifies processes, emits Snapshots
control.rs ProcessController port + the nix-backed signal adapter
classifier/ Per-family detectors (Chrome, Firefox, Electron, Java, Python, …) that turn argv into a runtime Platform, a friendly label, and an app-group identity
ui/ Renderer + IconSet ports, the interactive tui/ renderer, the plain snapshot renderer, and the icon glyph table

Sampling runs on a tokio task because sysinfo's process refresh can take 50–200ms on busy systems — running it on the main loop would freeze key input. Snapshots flow over an mpsc channel; the UI task awaits them in tokio::select! alongside the crossterm EventStream and a redraw timer.

Process control and clipboard access are behind traits, so the core's selection, pid, and signal logic is unit-tested with a recording fake. No real processes are signalled in the test suite.

Not implemented

  • No CSV/JSON export. If you want to script over the data, top -b -n 1 or ps is probably what you want anyway.
  • No filtering by user, command, or cgroup. Easy to add — open an issue or hack App::rank_top.
  • No remote / SSH process control. Run it on the host you care about.
  • Linux/macOS in practice. sysinfo is cross-platform, but nix::sys::signal::kill ties us to Unix. Windows support would need a small #[cfg] swap.

License

Licensed under either of

at your option.

About

TUI that ranks top CPU-hogging processes over a growing window and lets you kill them

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0