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.

brew install iprajax/oomtop/oomtop

Homebrew goes live with the first tagged release. Today: build from source (Rust 1.88+).

What it answers

Four questions htop can't answer.

What's really using my memory?

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).

oomtop TUI: htop-style per-core meters, true-memory bar, an answer-first headline, groups ranked by what matters, and an F-key bar
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 the recorded M5 Air: ranked groups, the Reclaim view with idle Gradle and Kotlin daemons, sandboxes and models views
    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
    8.0 GiB
    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.

    exitmeaning
    0fits now
    3fits after reclaim: it names exactly what to stop and how much that frees
    4doesn't fit, with the shortfall
    1 / 2couldn't measure / usage error
    oomtop headroom ‑‑model ~/models/qwen2.5‑14b‑q4_k_m.gguf ‑‑ctx 8192 && ./start‑server.sh
    oomtop headroom --need 13G answers No (exit 4), 8G answers Yes after reclaiming the two daemons (exit 3), 2G answers Yes (exit 0)
    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 lists GradleDaemon ≈3.0 GiB and KotlinCompileDaemon ≈2.7 GiB, total ≈5.8 GiB; oomtop why reports nothing wrong
    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 calls can_fit for 13 GB and gets a structured 'no, short by 1.8 GiB even after reclaiming 5.8 GiB'; suggest_reclaim lists the two daemons
    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.

    oomtop doctor lists each data source as ok, partial or unavailable with the reason, and the detected terminal capabilities
    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.

    oomtop theme list, then the TUI in the ember theme and in the monochrome none theme

    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.

    How it works

    No daemon. Pure core. Replayable.

    1. SourcesmacOS: proc_pid_rusage · sysctl · vm_statistics64 · IOReport · IOKit
      Linux: /proc · smaps_rollup · cgroup v2 · PSI · NVML · DRM fdinfo
      I/O, ≤ 50 ms each, no root
    2. RawSamplewhat fixtures recordreplays on any OS in CI
    3. Attributionrules · markers · ancestry · lineage + model-server & sandbox adaptersadapters talk to 127.0.0.1 only
    4. oomtop-coreheadroom · forecast · why · rankingpure, unit-tested
    5. OutputsTUI · json / ndjson · serve (HTTP + Prometheus) · MCP (stdio)same numbers everywhere
    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.

    git clone https://github.com/iprajax/oomtop && cd oomtop
    # Rust 1.88+; binary: target/release/oomtop
    cargo build --release -p oomtop-cli
    ./target/release/oomtop
    # or: cargo install --path crates/oomtop-cli --locked

    Try it against the recorded machine without touching yours: ./target/release/oomtop --replay fixtures/macos/m5-air-agents.json

    PlatformNotes
    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.28NVIDIA 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

    Capabilityoomtophtop / btopActivity Monitoragtopmacmon / 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 onlyquit only––
    MCP server for agents✓––––
    Token / cost trackingnot 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.