ktop 0.1.7

A fast Rust top/htop replacement with a Scrin TUI and Aisling effects.
Documentation

ktop

ktop is a fast Linux top/htop-style process monitor written in Rust. It has a full Scrin-powered TUI, Aisling color/effect passes, a spotlight grep overlay, mouse actions, anomaly detection, process tree mode, and non-TUI CLI fast paths for grep/kill workflows when the system or terminal is under stress.

Install

cargo install ktop

From source:

cargo run --release

CLI Fast Paths

Use these when the terminal is degraded, the TUI is not wanted, or you need a quick process action from scripts:

ktop --grep 'cmd:python user:root'
ktop --kill 'cmd:firefox' --signal TERM
ktop --kill 1234 --signal KILL --yes
ktop --anomalies --limit 20
ktop --version
ktop --diagnostics
ktop --stability-check --samples 120 --interval-ms 500

--kill accepts either a PID, comma-separated PIDs, or a spotlight query. It prints matches, asks for confirmation unless --yes is provided, and delivers signals directly with libc::kill.

Supported signals: TERM, KILL, STOP, CONT, INT, HUP.

--diagnostics prints the current sample size, ktop RSS, sampler cache sizes, sample cap-hit state, and configured resource caps.

--stability-check repeatedly samples /proc without opening the TUI and reports ktop RSS, process counts, thread high-water marks, cache high-water marks, and whether sample caps were reached. Output is bounded to a summary so the check can run in terminals without growing scrollback indefinitely.

TUI Controls

  • q or Esc: quit
  • / or Ctrl+F: open the spotlight grep overlay
  • j/k, arrow keys, PageUp/PageDown, Home/End: navigate processes
  • Mouse hover: show quick actions for a process row
  • Left click: select a process row
  • Right click: open the signal palette for that process
  • Middle click: confirm SIGTERM for that process
  • T: toggle process tree mode with matching ancestors shown for filtered results
  • A: toggle anomaly view for high-resource or suspicious process states
  • e: toggle lightweight Aisling matrix/glitch/burn effects
  • d: toggle the selected-process detail pane on wide terminals
  • c, m, p, n, u, t, a: sort by CPU, memory, PID, name, user, threads, or age
  • Tab: cycle sort mode
  • r: reverse sort direction
  • Space: pause or resume refreshes
  • g: force refresh
  • s: open the signal palette for TERM, KILL, STOP, CONT, INT, and HUP
  • K: confirm and send SIGTERM to the selected process
  • x: clear the active filter

Spotlight Grep

The overlay filters live as you type. Plain words match PID, user, process name, or command line. Field tokens are supported:

  • user:root
  • name:ssh
  • cmd:python
  • pid:123
  • ppid:1
  • uid:1000
  • state:R
  • age>2h, age<10m
  • cpu>20, cpu<5
  • mem>1, mem<10
  • !token to exclude matches

The same query style is used by --grep and query-based --kill.

Views

The header shows sort mode, view mode, load averages, process count, and thread count.

Wide terminals show a process detail deck with CPU/memory bars, identity fields, anomaly score, process age, boot-relative start time, RSS/VIRT, thread count, tree depth, and wrapped command text.

The top meter area keeps compact CPU and memory trend strips plus process state counts so spikes and lifecycle issues are visible over recent refreshes.

Anomaly view highlights high-resource or suspicious process states. The anomaly score is based on CPU, memory, state, thread pressure, and young hot processes.

Performance And Resilience

  • Scrin reuses frame buffers across draws.
  • Scrin diffs frames and writes only changed terminal cell runs.
  • Aisling effects are sparse and update only a few animated cells per frame.
  • Scrin frame buffers are capped even if a terminal reports pathological dimensions.
  • Tree view uses an explicit stack instead of recursive traversal.
  • TUI CPU and memory histories are ring buffers capped at 96 samples.
  • Spotlight input is capped, and parsed queries are capped by token count and token size.
  • CLI output limits are capped to avoid unbounded terminal scrollback.
  • Process and CPU samples have explicit hard caps.
  • /proc text reads have explicit byte caps.
  • /proc/[pid]/cmdline reads are bounded.
  • Retained process metadata strings have explicit byte caps.
  • The /etc/passwd user cache is loaded with explicit byte, entry, and username limits.
  • Process metadata is retained only while the same PID/start-time pair remains live.
  • CLI PID killing does not take a full process sample.
  • Signals are sent directly without spawning /bin/kill.
  • CPU-based CLI anomaly checks take a short second sample for meaningful deltas.
  • --diagnostics exposes current cache sizes, cap-hit state, and configured resource caps.
  • --stability-check exposes RSS, cap-hit state, and cache high-water marks across repeated samples.

Platform

ktop currently targets Linux and reads process data from /proc.