Linux process monitor

proctop watches a whole process tree.

proctop watches one process and its process tree (all children, recursively) and records CPU and memory usage over time — as a live TUI graph or as a plain, colored, or JSON line stream. Peaks are tracked and a summary is printed on exit.

Install Browse the source

Early days: no tagged release yet — install from main. Linux only (reads /proc). AGPL-3.0-or-later.

proctop firefox

proctop — firefox (pid 202378, 24 procs)    ⏸ paused (still recording) · interval 1s · elapsed 12:10

CPU  23.0%      min 15.0%  max 178.5% @17:07:49
                                     ▁                                                 █
                                     █▆▇▆                                              █
                                    ▄████    ▁                                 ▄▂      █
  ▂▁▂▂▂▁▂▃▁ █▁▂▁▁▅▁▃▁ ▃▁▃▁▁▁▆▃▂ ▂ ▄▃█████▆▆▄▇█▂▂▁▃▂▂▁▃▂▃▂▃▄▃▂▁▄▂▃▂▃▂▃▂▁▃█▁▁▄▂▃▃██      █         ▆
  ███████████████████████████████████████████████████████████████████████████████▅▆▆▅▅▆█▄▅▄▆▅▄▇▅▄█▇▆
MEM  3.4GiB     min 3.3GiB  max 3.8GiB @17:10:33
  ██████████▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇███████████▇▇▇█████████████████████▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▆▆▆▆▆▅▅▅▅▅▆▆▅
  ██████████████████████████████████████████████████████████████████████████████████████████████████
  ██████████████████████████████████████████████████████████████████████████████████████████████████
  ██████████████████████████████████████████████████████████████████████████████████████████████████
  ██████████████████████████████████████████████████████████████████████████████████████████████████
▶ 17:08:01 cpu 27.0% mem 3.3GiB
● 17:06:57–17:07:03 cpu 0.0% mem 0B — note 1
● 17:07:46–17:07:51 cpu 0.0% mem 0B — note 2

A real captured frame ([s] writes .txt and .ansi screenshots): 24 Firefox processes over 12 minutes, paused mid-recording, with the cursor parked on a sample and two annotated spans.

What it does

One binary, no daemon, no agent. Point it at a name or a PID and it follows the whole tree from there.

🌳

Whole-tree sampling

Follows a process and every descendant. The tree is re-discovered every tick, so processes that fork after you start are picked up automatically.

📈

Live TUI graph

CPU% and RSS drawn as scrolling sparkline bars, with running min, max, and the timestamp each peak occurred at.

🧾

Three line formats

plain, color, and json streams — one sample per line. Piping to a file or another process switches to stream mode on its own.

🏔️

Peaks and summary

Max, min, and average for both CPU and memory, with peak timestamps. Printed on exit and optionally appended to a JSON file.

📌

Marks and notes

Pause, scroll back through history, mark a span with v, and attach a note with a. Annotations land in the JSON summary.

📸

Screenshots

s writes the current frame to both a plain .txt and a colored .ansi file — paste-ready for bug reports.

Usage

proctop [flags] <name|pid> — exactly one target. A name resolves to the topmost match with the largest subtree.

$ proctop firefox            # live TUI graph (q to quit)
$ proctop 4242               # watch by PID
$ proctop -f plain firefox   # stream one line per second
$ proctop -f json  firefox   # JSON lines for machine consumption
$ proctop -o usage.log -s summary.json firefox   # export samples + summary

Flags

Flag	Default	Description
`-i, --interval`	`1s`	sampling interval
`-f, --format`	`color`	line format: plain\|color\|json (implies `--stream`)
`-o, --out`	—	append per-sample lines to this file
`-s, --summary`	—	append JSON summary to this file on exit
`-n, --history`	`300`	samples kept for graph and history
`--stream`	`false`	print sample lines instead of the TUI

Keys in the live graph

Pausing keeps recording — you can scroll back through history without losing samples, then resume.

q quit p / space pause & play s screenshot ← → move cursor / scroll time v mark a span a annotate + / - interval up & down enter / esc save & cancel a note

How it works

Sampling

Reads /proc/<pid>/stat for every process in the tree, once per interval. No ptrace, no kernel module, no elevated privileges for your own processes.

CPU%

Deltas of utime + stime ticks, expressed as percent of a single core and summed across the tree — so a busy multi-core tree legitimately exceeds 100%.

Memory

RSS pages converted to bytes and summed. Shared pages are counted once per process, so tree totals over-report shared memory — treat it as an upper bound.

Install

Go 1.26 or newer. There is no tagged release yet, so @latest tracks the tip of main.

$ go install codeberg.org/ubunatic/proctop@latest

# or from a clone
$ git clone https://codeberg.org/ubunatic/proctop
$ cd proctop && make install