Linux process monitor

proctop watches a whole process tree.

proctop watches one process and its descendants and records CPU and memory over time. Follow a live TUI graph or stream plain, colored, or JSON samples; peaks and a summary are tracked on exit.

go install codeberg.org/ubunatic/proctop@latest

Install Browse the source

Project snapshot · measured 2026-10-26

Key facts

Commits 23Last commit 2026-10-06 Source receipt ↗ Commits · 7 days 0 Source receipt ↗ Tickets closed 0 / 16 Source receipt ↗ Studies 1 Source receipt ↗

12-week commit activity

2026-10-26

Aug 3

Aug 10

Aug 17

Aug 24

Aug 31

Sep 7

Sep 14

Sep 21

Sep 28

Oct 5

Oct 12

Oct 19

View 12-week data table

Week starting	Commits
2026-08-03	2
2026-08-10	0
2026-08-17	0
2026-08-24	3
2026-08-31	1
2026-09-07	0
2026-09-14	0
2026-09-21	0
2026-09-28	0
2026-10-05	1
2026-10-12	0
2026-10-19	0

Key Features

Live terminal graphs with pause, time-range selection and notes.
Exports plain text, colored text or JSON for other tools.

Stack

Go 1.26.5, Cobra, x/term, YAML + JSON Schema, Linux /proc, GoReleaser

Recorded TUI frame

A real capture of Firefox and its child processes

This frame was captured after twelve minutes of recording. The display is paused while sampling continues; the cursor is parked on a sample and two spans carry notes.

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

Features

Follow, inspect and export a process tree

Whole-tree sampling

Follows every descendant and rediscovers the tree every tick, including processes that fork later.

Live TUI graph

CPU and RSS sparklines with running minimum, maximum and peak timestamps.

Stream formats

Plain, colored and JSON samples; piping output switches to stream mode automatically.

Peaks and summary

CPU and memory min, max and average, with peak timestamps, printed on exit or appended to JSON.

Marks and notes

Pause, scroll history, mark a span with v, and annotate with a; annotations appear in the JSON summary.

Screenshots

Press s to save the current frame as plain .txt and colored .ansi files.

Usage

Watch by process name or PID

proctop [flags] <name|pid> accepts exactly one target. A process 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

Flag	Default	Description
`-i, --interval`	`1s`	Sampling interval
`-f, --format`	`color`	`plain`, `color`, or `json` stream format
`-o, --out`	—	Append per-sample lines to this file
`-s, --summary`	—	Append a JSON summary on exit
`-n, --history`	`300`	Samples kept for graph and history
`--stream`	`false`	Print samples instead of the TUI

TUI keys

Navigate the live graph

Quit.

p / space

Pause and resume recording.

left / right

Move the cursor and scroll through time.

Mark a span.

Add a note.

enter / esc

Save or cancel a note.

+ / -

Increase or decrease the sampling interval.

Save a screenshot to .txt and .ansi files.

How it works

Sample Linux process statistics

Sampling

Reads /proc/<pid>/stat for each process once per interval; no ptrace, kernel module, or elevated privileges are needed for your own processes.

CPU

Uses deltas of utime + stime ticks, as a percentage of one core summed across the tree; multi-core trees can exceed 100%.

Memory

Sums resident-set pages converted to bytes. Shared pages are counted per process, so treat the tree total as an upper bound.

Install

Install with Go or from a clone

Requires Go 1.26 or newer. proctop is Linux-only because it reads /proc.

go install codeberg.org/ubunatic/proctop@latest

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

Engineering story

Building a process monitor

Read the proctop engineering story.

Project details

Stack

Go 1.26.5, Cobra, x/term, YAML + JSON Schema, Linux /proc, GoReleaser

Source

https://codeberg.org/ubunatic/proctop ↗

Architecture

Layer composition

Terminal: TUI, ANSI graph
Desktop: Linux, /proc
Inference / AI: —
Containers / VM: —
Web: —

Engineering story

proctop: the story behind the project

A process monitor usually answers one narrow question: what is using resources right now? proctop was built to answer a more useful debugging question: how did one application and all of its child processes behave over time? It watches CPU…

Read the engineering story

Measurement source · 2026-10-26

Verification receipts

Commits: 23 · Last commit 2026-10-06
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Commits · 7 days: 0
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Tickets closed: 0 / 16
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Studies: 1
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
12-week commit activity
git rev-list --count --since=<Monday> --until=<Sunday> HEAD
12 latest complete ISO weeks; weekly values are from spec/metrics.yaml.