proc-stats

A Claude Code mod that pins a status line with the session's own resource use, and opens a task-manager pane of it on /proc-stats:

mem 484MB · peak 530MB · cpu 2.4% · up 12m 4s

While the session has processes running under it (Bash commands, watchers, test runs, local MCP servers), or ones it started that have since detached, their share is added after a +:

mem (484 + 215)MB · peak 530MB · cpu (2.4 + 98.7)% · up 12m 4s

• mem: resident memory of Claude Code, plus every process below it and every detached process it started.
• peak: Claude Code's highest resident memory. On macOS, where ps has no peak, it is the highest seen since the mod loaded.
• cpu: share of one core since the last reading, as top shows it.
• up: how long Claude Code has been running.

Processes pane

/proc-stats opens a task-manager pane and gives it the keyboard (Esc hands it back to the prompt; click the pane or press ctrl+x then tab to return):

• History: two lines at the top chart the session's total memory and CPU (Claude Code and everything it started) over the history window (10 minutes by default; see Settings), each followed by the current value and the window's highest (max). Memory is scaled from the window's lowest to its highest point, and never to less than 64 MB or a tenth of its highest point (whichever is more), so a slow leak rises across the full height while small noise stays flat and a steady line sits mid-height; CPU is scaled from zero to one core, or to its highest point when that is more. Short spikes stay visible. Readings are drawn evenly spaced, so a gap (such as while the machine sleeps) does not show.
• Rows: Claude Code's own row, then every process below it as a tree. A Bash command Claude ran shows as $ <command>; a $ … row also says what started it when it can tell — · Bash, · Monitor, · subagent: <type>, or · agent for one it cannot name — and the details name the subagent's task (commands started before the mod loaded show none); ▾/▸ marks a row with processes under it. Under the rows, Child processes sums every process below Claude Code, and Total adds the detached ones and Claude Code's own.
• Detached: processes the session started that no longer run under Claude Code (nohup … &, setsid, daemons) follow the tree under a Detached heading, with their own subtotal. They count toward the totals, the history, the status-line marker and the toasts, and can be stopped like any other row. In a sorted view their parent reads detached. The mod finds them by a variable, PROC_STATS_SESSION, that it sets for every command the session starts; if it cannot set it, a line under the rows says detached processes are not tracked.
• ↑ / ↓ move between rows; the row you land on is selected and its full command, pid, parent, start time, memory and CPU show under the table, with what started it and whether it is detached.
• Enter or a click selects a row, and on a row with processes under it collapses or expands it (collapsed, it shows its subtree's totals).
• s sorts by CPU, memory or runtime (highest first, each row followed by its parent), then back to the tree.
• k stops the selected process and everything it started: it asks first (y Stop, n Cancel; Esc, leaving the pane, cancels too), sends SIGTERM (Windows: taskkill /T), and after 3 seconds offers f Force stop (SIGKILL) if anything is still running, even a process that left the tree when its parent ended. Once a stop is sent the footer offers n Dismiss. Claude Code's own row cannot be stopped.
  • Stopping a $ … row that Claude is still running ends that tool call.
  • A stop reaches only the first 500 listed processes.
  • On Windows a first stop may need f: taskkill without /F cannot end console processes.

TIME, then PID, give way on a narrow pane.

Report

/proc-stats report writes a summary of the session into the conversation, where Claude reads it too: the platform and how long Claude Code has run; the memory and CPU of Claude Code, its child processes, its detached processes and all of them together now; the highest memory and CPU of the history window and how long ago they were; the five processes using the most memory, with what started them; up to ten detached processes; the marker level; and the last five alerts.

Platforms

By default both views refresh every second on Linux, every 2 seconds on macOS and every 5 on Windows (configurable in Settings), and work on Linux (/proc and ps), macOS (ps) and Windows (PowerShell). Detached processes are found on Linux (/proc/<pid>/environ, read once per process) and macOS (ps eww, at most every 10 seconds, so a new one can take that long to show), and not on Windows.

Settings

In Claude Code's config menu (/config), under proc-stats:

A value out of range is ignored and its default used.

Alerts

• Status line: 🟡 at the start of the line when the session (Claude Code and every process it started) uses more memory than the warning limit, or more CPU on average over the last 10 seconds (two refreshes when the refresh is slower); 🔴 above the alert limit. A marker clears only once its value is 10% below the limit, so it does not flicker.
• Toasts: one when a process the session started (under Claude Code or detached) stays above the busy-process CPU limit for the set time (short dips are tolerated), and one when it grows past the large-process memory limit. Each fires once per process, and again only after the process has been 10 seconds below 90% of the limit. Several at once become one toast.

Install

At the prompt of a Claude Code terminal session:

/plugin install proc-stats --marketplace DragosMocrii/proc-stats

Answer y to add the marketplace, then choose a scope (user scope loads it in every session).

Limits

• A detached process is found only if it keeps the environment it started with (a program that clears it, such as env -i, is not found), and only on Linux and macOS.
• A program a command opens that outlives it, such as a browser or editor started by xdg-open or code ., carries the session's mark and is counted as a detached process.
• A command that starts and ends between two readings is not counted.
• + ? means the process table could not be read (for example no ps in a minimal container).

FAQ

Does it add much overhead? Little. Each reading runs ps once. On Linux it also reads a few small /proc files for Claude Code and for each process under it, and reads a new process's environment once. A reading that is due while the last one is still running is skipped, so readings never pile up. With 36 processes running, one ps call takes about 5 ms. Windows costs more because every reading starts PowerShell, so it reads every 5 seconds by default. The mod only reads: it attaches to no process, does not slow any process down, and sends nothing over the network. It runs inside Claude Code, so its own memory and CPU show in Claude Code's row. It keeps at most 2,400 history points and 500 rows. For a lighter load, raise the refresh in Settings.

Is it configurable? Yes, in /config under proc-stats. You can set how often each platform is read, the memory and CPU limits for the 🟡 / 🔴 markers and the toasts, how far back the history goes, and whether the status line shows the + part for child processes. See Settings.

Can I resize the pane? Yes. Claude Code places the pane and sizes it, not the mod. In the fullscreen layout at 110 columns or more, it docks beside the conversation; otherwise it sits above the prompt. You can drag it to another size, and Claude Code keeps the size you set. When the pane is narrow, the TIME column is hidden first, then PID.

Why is CPU above 100%? CPU is a share of one core, as in top, so 250% means two and a half cores are busy.

Does it see my other sessions and terminals? No. It sees Claude Code, the processes under it, and detached processes that carry this session's mark. Each session gets its own mark, so another session's processes are not counted.

What is PROC_STATS_SESSION in my environment? It is this session's mark, a random ID that the mod sets for every command the session starts. The mod uses it to find processes that have detached. It holds nothing else.

Can it stop a process by mistake? No. It stops a process only when you press k on its row in the pane and then confirm with y. Claude Code's own row cannot be stopped.

Development

claude plugin validate .
claude plugin test .
claude --plugin-dir .

docs/demo.gif is recorded by docs/demo, a Go module that runs Claude Code with the mod in a pseudo-terminal, in a made-up project whose stand-in processes hold memory and CPU, and draws the screen to a GIF. It runs on Linux, logged in to Claude Code (its one prompt uses your account), in a home and config directory of its own; see the comment at the top of docs/demo/main.go for the fonts it needs. Re-record it after visible changes:

cd docs/demo
go run . -font DejaVuSansMono.ttf -bold DejaVuSansMono-Bold.ttf \
  -fallback DejaVuSans.ttf,NotoSansSymbols2-Regular.ttf,NotoSansSymbols.ttf -emoji noto-emoji/2D/png/72