# 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

```bash
cargo install ktop
```

From source:

```bash
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:

```bash
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.
- 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 and entry 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`.
