Terminal resource monitor ·macOS + Linux · no root
See the OOM coming.
htop for local AI work. See what really holds your RAM (GPU/Metal, compressed,
swap), which agent, app or model server owns every process, and whether the next model will fit — before it swaps.
Footprint and PSS, not RSS — including GPU/Metal, compressed and swapped memory, grouped by owner.
$ oomtop
Will this model fit right now?
Yes, yes-after-reclaim or no, with the shortfall and an exit code for scripts.
$ oomtop headroom --need 13G
What can I safely stop?
Idle build daemons, orphans left by agent sessions, idle model servers — largest gain first, always confirmed.
$ oomtop reclaim --dry-run
Why is it slow?
Swap storms, memory pressure, thermal throttling, Low Power Mode — ranked, with evidence, plus an OOM forecast.
$ oomtop why
▲ Tight on memory: 1.2 GB headroom. sd-server holds 9.9 GB; 2 idle build daemons could free 5.9 GB. r
The first line oomtop shows: the answer, then the numbers.
What you get
An htop you already know, telling the truth about memory.
01
An htop you already know how to read
Per-core bars (tagged E/P on Apple Silicon), Mem[…] and Swp[…] meters,
Tasks · Load · Uptime, and the familiar F1–F10 bar: Help, Setup, Search, Filter, Tree, SortBy, Why,
Reclaim, Stop, Quit. It works in every key preset (default, vim, emacs, htop).
Live TUI: per-core meters, a memory bar split by what holds RAM, a one-line verdict, grouped processes.
02
Memory that tells the truth
The Mem bar is split by what really holds RAM. The glyphs differ, so it reads without color. Per process:
macOS phys_footprint (includes Metal), Linux PSS/SwapPss + NVML/DRM GPU memory. Never RSS alone, and every
number carries its source.
Mem[]
From the recorded snapshot. Each figure keeps its source, e.g. app = vm_statistics64: internal − purgeable.
03
Things, not PIDs: every process has an owner
Every process is grouped under its agent session (Claude Code, Codex, Cursor, Aider, Gemini…),
app, model server (Ollama, llama.cpp, sd.cpp, vLLM, LM Studio, MLX), sandbox
(VMs, Docker/OrbStack/Podman, Firecracker) or build daemon. Leftovers from ended sessions show as
orphans; memory that does nothing shows as idle, sorted by what you'd get back.
Replay of a recorded snapshot: oomtop --replay fixtures/macos/m5-air-agents.json
04
“Can I load this model now?”, answered in one command
Headroom = what the OS can give you now, minus a safety margin. On Apple Silicon it also checks the Metal GPU
budget. Give it bytes or a model file: --model x.gguf reads only the GGUF header (layers, KV heads, context)
to estimate weights + KV cache + buffers. The exit code is made for scripts.
Try it on the recorded machine
computed from the recorded snapshot · data/snapshot.json
headroom now
after reclaim
your need
$oomtop headroom --need 8.0G
exit 3
Uses the snapshot's headroom () and the reclaim plan oomtop computed
(largest gain first). The real command re-samples your machine; answers are advisory and valid for ~10 s.
exit
meaning
0
fits now
3
fits after reclaim: it names exactly what to stop and how much that frees
The same three answers in a real terminal: 13G no (exit 4), 8G yes after reclaim (exit 3), 2G yes (exit 0).
05
Reclaim safely, and know why it's slow
Reclaim lists idle build daemons, orphans and idle model servers, largest gain first, with the RAM you'd
actually get back (an estimate, and labeled as one). Nothing is stopped without confirmation. Model servers are unloaded
through their own API first (e.g. Ollama keep_alive: 0), then SIGTERM. SIGKILL needs a second, explicit yes.
oomtop why ranks causes with evidence: swap storms (+600 MB/min), memory pressure / PSI, thermal
pressure, Low Power Mode, battery, GPU clocks. Throttling is only reported under load, since Apple
Silicon also down-clocks when idle.
OOM forecast: when swap or available memory trends steadily toward a killer's threshold (kernel OOM,
systemd-oomd, earlyoom, macOS jetsam), the headline says “Swap full in ~6 min at this rate” and names the likely
victim. A single spike never triggers it.
oomtop reclaim --dry-run on the recorded machine, then oomtop why.
06
Agents ask before they load (MCP)
$ claude mcp add oomtop -- oomtop mcp
Read-only tools: get_headroom, can_fit, top_consumers, list_groups,
list_model_servers, list_sandboxes, explain_slowdown, suggest_reclaim. With
--allow-actions there is also reclaim, and oomtop itself asks you through MCP elicitation before
stopping anything. It samples only when called, so four agents running four MCP servers cost nothing while idle.
Setup for Codex, Cursor and Claude Desktop: docs/mcp.md.
An MCP client calling can_fit and suggest_reclaim: structured answers, no side effects.
07
Honest about what it can't see
oomtop doctor lists every source as ok / partial / unavailable (reason) and every terminal capability it
detected. Missing data is shown as n/a with a reason, never as a silent zero.
08
Your terminal is the theme
The default terminal theme uses your terminal's own 16 colors and never paints a background. Opt-in
themes: mono, ember, mint, sand, coral, high-contrast,
colorblind, none. Import base16, iTerm2, Ghostty, Kitty or Alacritty themes. NO_COLOR,
--plain (screen readers) and --ascii are supported.
Keyboard
The F-key bar you already know
Press a key or pick one. On macOS the F-keys may control brightness/volume: use fn+F-key, or the letter keys.
0.96 %of one core for the TUI, measured on the M5 Air over 11 minutes
31 MBRSS for the TUI (headless: 0.8 %, 24 MB)
0.2 %footprint delta vs. top on the M5 Air
737tests pass on macOS; 689 on Linux aarch64 (1 skipped)
Install
One static binary. No root.
Pre-release (v0.1.0). Build from source today. Release archives, the Homebrew tap and the install
script go live with the first tagged release; those tabs say so.
Try it against the recorded machine without touching yours: ./target/release/oomtop --replay fixtures/macos/m5-air-agents.json
brew install iprajax/oomtop/oomtop
From the tap iprajax/homebrew-oomtop; the formula is rendered from the release's SHA256SUMS. Available after the first tagged release; homebrew-core after 1.0.
curl -fsSL https://github.com/iprajax/oomtop/releases/latest/download/install.sh | sh
POSIX sh. Picks the glibc or static musl build, verifies the archive against SHA256SUMS and refuses to install on a mismatch, installs to ~/.local/bin without sudo. Options: --version, --to DIR, --musl, --dry-run. Available after the first tagged release.
cargo install oomtop-cli --locked # installs the `oomtop` binary
From crates.io after the first release. Today, cargo install --path crates/oomtop-cli --locked from a clone.
oomtop-<v>-x86_64-unknown-linux-gnu.tar.gzglibc ≥ 2.28, NVML at runtime
oomtop-<v>-aarch64-unknown-linux-gnu.tar.gzglibc ≥ 2.28, NVML at runtime
oomtop-<v>-x86_64-unknown-linux-musl.tar.gzfully static, no NVML
oomtop-<v>-aarch64-unknown-linux-musl.tar.gzfully static, no NVML
.deb · .rpm · SHA256SUMSbuilt from the glibc binaries
On GitHub Releases after the first tagged release. macOS builds are codesigned and notarized when the signing secrets are configured.
Platform
Notes
macOS 13+ on Apple Silicon (primary)
GPU/power via IOReport (resolved at runtime; degrades cleanly). Intel Macs: best effort
Linux x86_64 / aarch64, glibc ≥ 2.28
NVIDIA via NVML (loaded at runtime), AMD/Intel via DRM fdinfo, PSI, cgroup v2
Linux, fully static (musl)
everything except NVML
Use
oomtop
the TUI
oomtop headroom --need 13G
exit 0 yes · 3 after reclaim · 4 no
oomtop why
ranked causes of slowness / pressure, with evidence
oomtop reclaim --dry-run
what's idle and what stopping it would free
oomtop models
model files on disk: size, last use, duplicates
oomtop json
one redacted, versioned snapshot (ndjson: one per interval)
oomtop serve
HTTP JSON + Prometheus /metrics on 127.0.0.1:9469
oomtop mcp
MCP server for agents
oomtop doctor
what was measured, what wasn't, and why
How it compares
The attribution + headroom layer
Capability
oomtop
htop / btop
Activity Monitor
agtop
macmon / mactop
macOS footprint / Linux PSS (not RSS)
✓
–
✓
–
–
Apple GPU / power, no sudo
✓
–
partial
–
✓
Processes grouped by agent session / app / sandbox / model server
✓
–
–
agents only
–
“Can I load X GB?” + script exit codes
✓
–
–
–
–
OOM forecast with the likely victim
✓
–
–
–
–
Safe reclaim of idle daemons / orphans
✓
kill only
quit only
–
–
MCP server for agents
✓
–
–
–
–
Token / cost tracking
not a goal
–
–
✓
–
Safety and privacy
Nothing stops without your yes. Nothing leaves your machine.
Confirm, then SIGTERM
Actions target whole groups, with the identity re-checked (pid + start time) right before signalling. SIGTERM first;
SIGKILL only on a second explicit yes. System processes, your terminal, other users' processes and the asking agent session are protected.
Redacted by default
Command lines are redacted in every export. Environments are read only for an allowlist of session-marker keys (hashed, never stored).
MCP is read-only unless you pass --allow-actions.
Local only
No telemetry. serve binds 127.0.0.1. Learning (what you open and pin) is local SQLite: --no-learn turns it
off, oomtop profile reset forgets it.
Know before it swaps.
Open source, MIT licensed, built in the open. Read the spec, file an issue, or run it against the recorded machine.