memtaskman 0.1.0__py3-none-any.whl

memtaskman/__init__.py

@@ -0,0 +1,3 @@
+"""memtaskman: an htop for what's inside your RAM, not just how full it is."""
+
+__version__ = "0.1.0"

memtaskman/__main__.py

@@ -0,0 +1,3 @@
+from memtaskman.cli import main
+
+raise SystemExit(main())

memtaskman/app.py

@@ -0,0 +1,505 @@
+"""Textual TUI."""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from pathlib import PureWindowsPath
+
+from rich.console import Group
+from rich.table import Table
+from rich.text import Text
+from textual import work
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import Grid, Horizontal, Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import DataTable, Footer, Sparkline, Static
+
+from memtaskman.collector import LINUX, WINDOWS, Collector, group_by_app, sort_procs
+from memtaskman.fmt import fmt_bytes, fmt_count_rate, fmt_rate, pct
+from memtaskman.model import DERIVED, HINT, IDENTIFIED, MEASURED, Inspection, ProcessMem, Snapshot, SystemMemory
+
+HISTORY = 120
+TOP_N = 50
+INSPECT_EVERY = 5.0
+
+C_USED = "#4e9af1"
+C_MOD = "#e5a50a"
+C_STANDBY = "#57a773"
+C_FREE = "#3a3f4b"
+C_COMMIT = "#b48ead"
+C_SWAP = "#d08770"
+
+CHARTS = [
+    ("used", "RAM in use", "bytes"),
+    ("commit", "Commit charge", "bytes"),
+    ("cache", "Standby / cache", "bytes"),
+    ("compressed", "Compressed", "bytes"),
+    ("swap", "Swap / pagefile used", "bytes"),
+    ("kernel", "Kernel pools", "bytes"),
+    ("faults", "Page faults/s", "rate"),
+    ("hard", "Hard faults/s (disk)", "rate"),
+]
+
+LEVEL_STYLE = {MEASURED: "green", DERIVED: "cyan", IDENTIFIED: "magenta", HINT: "yellow"}
+
+HELP = f"""\
+[b]memtaskman[/b] — what is inside your RAM
+
+[b]System bar[/b]
+  [{C_USED}]■ In use[/]     pages owned by processes, the kernel and drivers
+  [{C_MOD}]■ Modified[/]   dirty pages that must be written to disk before reuse
+  [{C_STANDBY}]■ Standby/cache[/]  file cache; instantly reusable, so it is "available"
+  [{C_FREE}]■ Free[/]       zeroed / free pages (Linux: MemFree)
+  Commit      memory promised to processes (RAM + pagefile); hitting the limit = out of memory
+  Compressed  Windows compression store / Linux zswap pool
+
+[b]Process columns[/b]
+  Resident    working set / RSS: this process's pages in RAM right now (shared pages counted in every sharer)
+  Private     Windows: private commit (heap, stacks; may be partly paged out)
+  Anon        Linux: resident anonymous memory (RssAnon)
+  PSS         Linux: resident, with each shared page split between its sharers; sums to real RAM use
+              (read from smaps_rollup for visible rows; blank for other users' processes unless run as root)
+  Growth      smoothed change of Private per second — a steadily positive value is how leaks look
+  Faults/s    page faults per second (soft + hard)
+  Pool/Swap   Windows: kernel pool charged to the process / Linux: swapped-out bytes
+
+[b]Inspector[/b] walks the selected process's address space:
+  Images      exe/DLL/.so code+data, mostly shared with other processes
+  Mapped      memory-mapped files (fonts, caches, model weights loaded with mmap)
+  Shared mem  pagefile-backed sections, /dev/shm, memfd
+  Private     heap, GC heaps, JIT code, anonymous mmap
+  Mapped = committed (Win) / mapped (Linux); Resident = in RAM; Shared = resident pages shared with others
+  Evidence: [green]measured[/] OS counter · [cyan]derived[/] computed by memtaskman ·
+            [magenta]identified[/] from loaded modules · [yellow]hint[/] a configured limit, not usage
+
+[b]Keys[/b]  ↑/↓ select  s sort  g group by app  a top/all  c charts  m slim  p pause  ? help  q quit
+[dim]Esc to close[/dim]"""
+
+
+class HelpScreen(ModalScreen):
+    BINDINGS = [Binding("escape,question_mark,q", "app.pop_screen", "Close")]
+
+    def compose(self) -> ComposeResult:
+        with VerticalScroll(id="help"):
+            yield Static(HELP)
+
+
+def stacked_bar(segments: list[tuple[str, int, str]], total: int, width: int) -> Text:
+    t = Text()
+    width = max(10, width)
+    used_cells = 0
+    for i, (_label, value, color) in enumerate(segments):
+        if i == len(segments) - 1:
+            cells = width - used_cells
+        else:
+            cells = round(width * max(0, value) / total) if total else 0
+            cells = min(cells, width - used_cells)
+        t.append("█" * cells, style=color)
+        used_cells += cells
+    return t
+
+
+def ram_segments(sm: SystemMemory) -> list[tuple[str, int, str]]:
+    if sm.standby is not None:  # Windows
+        mod = sm.modified or 0
+        in_use = max(0, sm.used - mod)
+        free = sm.free if sm.free is not None else max(0, sm.total - in_use - mod - sm.standby)
+        return [("In use", in_use, C_USED), ("Modified", mod, C_MOD), ("Standby", sm.standby, C_STANDBY), ("Free", free, C_FREE)]
+    if sm.cached is not None and sm.free is not None:  # Linux
+        in_use = max(0, sm.total - sm.free - sm.cached)
+        return [("In use", in_use, C_USED), ("Cache", sm.cached, C_STANDBY), ("Free", sm.free, C_FREE)]
+    return [("Used", sm.used, C_USED), ("Available", sm.available, C_FREE)]
+
+
+class MemTaskManApp(App):
+    TITLE = "memtaskman"
+    CSS = """
+    Screen { layout: vertical; }
+    #top { height: auto; padding: 0 1; }
+    #charts { grid-size: 4 2; grid-gutter: 0 2; height: 8; padding: 0 1; }
+    #charts.single { grid-size: 1 1; height: 10; }
+    .chart { height: 4; }
+    #charts.single .chart { height: 10; }
+    .chart Sparkline { height: 1fr; }
+    .chart .label { height: 1; color: $text-muted; }
+    #body { height: 1fr; }
+    #procs { width: 1fr; }
+    #side { width: 64; border-left: tall $panel; }
+    #system { height: auto; padding: 0 1; }
+    #inspector { height: 1fr; padding: 0 1; }
+    .slim #charts, .slim #side { display: none; }
+    HelpScreen { align: center middle; }
+    #help { width: 100; max-width: 95%; height: 80%; border: round $accent; background: $surface; padding: 1 2; }
+    """
+    BINDINGS = [
+        Binding("q", "quit", "Quit"),
+        Binding("s", "sort", "Sort"),
+        Binding("g", "group", "Group"),
+        Binding("a", "toggle_all", "Top/All"),
+        Binding("c", "charts", "Charts"),
+        Binding("m", "mode", "Slim"),
+        Binding("p", "pause", "Pause"),
+        Binding("question_mark", "help", "Help", key_display="?"),
+    ]
+
+    def __init__(self, interval: float = 1.0, system: bool = True):
+        super().__init__()
+        self.interval = max(0.25, interval)
+        self.collector = Collector(system=system)
+        self.history: dict[str, deque[float]] = {k: deque(maxlen=HISTORY) for k, _, _ in CHARTS}
+        self.sort_keys = ["resident"] + (["pss"] if LINUX else []) + ["private", "growth", "faults", "name", "pid"]
+        self.sort_key = "resident"
+        self.show_all = False
+        self.grouped = False
+        self.paused = False
+        self.chart_mode = -1  # -1 = all charts, else index into CHARTS
+        self.snapshot: Snapshot | None = None
+        self.rows: dict[str, ProcessMem] = {}
+        self.selected: str | None = None
+        self.last_inspect = 0.0
+        self.inspection: Inspection | None = None
+
+    # ------------------------------------------------------------------ layout
+    def compose(self) -> ComposeResult:
+        yield Static(id="top")
+        with Grid(id="charts"):
+            for key, label, _ in CHARTS:
+                with Vertical(classes="chart", id=f"chart-{key}"):
+                    yield Static(label, classes="label", id=f"label-{key}")
+                    yield Sparkline([], summary_function=max, id=f"spark-{key}")
+        with Horizontal(id="body"):
+            yield DataTable(id="procs", cursor_type="row", zebra_stripes=True)
+            with Vertical(id="side"):
+                yield Static(id="system")
+                with VerticalScroll(id="inspector"):
+                    yield Static("Select a process to see what its memory is made of.", id="inspect-body")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self._setup_columns()
+        self.set_interval(self.interval, self.tick)
+        self.tick()
+
+    def _setup_columns(self) -> None:
+        t = self.query_one("#procs", DataTable)
+        t.clear(columns=True)
+        pl = self.collector_private_label()
+        last = "Pool" if WINDOWS else "Swap"
+        first = "Procs" if self.grouped else "PID"
+        t.add_column(first, key="pid", width=7)
+        t.add_column("Name", key="name", width=26)
+        t.add_column("Resident", key="resident", width=9)
+        if LINUX:
+            t.add_column("PSS", key="pss", width=9)
+        t.add_column(pl, key="private", width=9)
+        t.add_column("Growth", key="growth", width=10)
+        t.add_column("Faults/s", key="faults", width=8)
+        t.add_column(last, key="extra", width=7)
+        t.add_column("Runtime", key="runtime", width=24)
+
+    def collector_private_label(self) -> str:
+        from memtaskman.collector import private_label
+
+        return private_label()
+
+    # ------------------------------------------------------------------ sampling
+    def tick(self) -> None:
+        if not self.paused:
+            self.sample()
+
+    @work(thread=True, exclusive=True, group="sample")
+    def sample(self) -> None:
+        snap = self.collector.sample()
+        visible = self._ordered(snap.processes)[: TOP_N if not self.show_all else None]
+        self.collector.resolve_runtimes(visible + sort_procs(snap.processes, "resident"), time_budget=0.3)
+        self.collector.refresh_pss(visible, time_budget=0.2)
+        self.call_from_thread(self.apply, snap)
+
+    def apply(self, snap: Snapshot) -> None:
+        self.snapshot = snap
+        if snap.system:
+            self._push_history(snap.system)
+        self.render_top()
+        self.render_charts()
+        self.render_system()
+        self.render_table()
+        if self.selected and time.monotonic() - self.last_inspect > INSPECT_EVERY:
+            self._inspect_selected()
+
+    def _push_history(self, sm: SystemMemory) -> None:
+        vals = {
+            "used": sm.used,
+            "commit": sm.commit_used,
+            "cache": sm.standby if sm.standby is not None else sm.cached,
+            "compressed": sm.compressed,
+            "swap": sm.swap_used,
+            "kernel": (sm.kernel_paged or 0) + (sm.kernel_nonpaged or 0) if sm.kernel_paged is not None else None,
+            "faults": sm.page_faults_ps,
+            "hard": sm.hard_faults_ps,
+        }
+        for k, v in vals.items():
+            if v is not None:
+                self.history[k].append(float(v))
+
+    # ------------------------------------------------------------------ rendering
+    def render_top(self) -> None:
+        snap = self.snapshot
+        top = self.query_one("#top", Static)
+        width = max(20, top.size.width - 2 if top.size.width else 100)
+        lines: list[Text] = []
+        status = Text()
+        status.append("memtaskman", style="bold")
+        status.append(f"  sort:{self.sort_key}  {'grouped by app' if self.grouped else 'per process'}"
+                      f"  {'all' if self.show_all else f'top {TOP_N}'}  {len(snap.processes)} processes", style="dim")
+        if self.paused:
+            status.append("  PAUSED", style="bold yellow")
+        lines.append(status)
+        sm = snap.system
+        if sm:
+            bar_w = width - 30
+            segs = ram_segments(sm)
+            line = Text(f"{'RAM':<7}")
+            line.append_text(stacked_bar(segs, sm.total, bar_w))
+            line.append(f" {fmt_bytes(sm.used)}/{fmt_bytes(sm.total)} {pct(sm.used, sm.total):.0f}%")
+            lines.append(line)
+            legend = Text(" " * 7)
+            for label, value, color in segs:
+                legend.append("■ ", style=color)
+                legend.append(f"{label} {fmt_bytes(value)}   ")
+            if sm.compressed is not None:
+                legend.append(f"Compressed {fmt_bytes(sm.compressed)}   ", style="dim")
+            lines.append(legend)
+            if sm.commit_used is not None and sm.commit_limit:
+                line = Text(f"{'Commit':<7}")
+                line.append_text(stacked_bar([("c", sm.commit_used, C_COMMIT), ("r", sm.commit_limit - sm.commit_used, C_FREE)],
+                                             sm.commit_limit, bar_w))
+                line.append(f" {fmt_bytes(sm.commit_used)}/{fmt_bytes(sm.commit_limit)} {pct(sm.commit_used, sm.commit_limit):.0f}%")
+                lines.append(line)
+            if sm.swap_total:
+                line = Text(f"{'Swap':<7}")
+                line.append_text(stacked_bar([("s", sm.swap_used or 0, C_SWAP), ("f", sm.swap_total - (sm.swap_used or 0), C_FREE)],
+                                             sm.swap_total, bar_w))
+                line.append(f" {fmt_bytes(sm.swap_used)}/{fmt_bytes(sm.swap_total)}")
+                lines.append(line)
+        top.update(Text("\n").join(lines))
+
+    def render_charts(self) -> None:
+        for i, (key, label, kind) in enumerate(CHARTS):
+            data = list(self.history[key])
+            cell = self.query_one(f"#chart-{key}")
+            cell.display = self.chart_mode in (-1, i)
+            if not cell.display:
+                continue
+            cur = data[-1] if data else None
+            if kind == "bytes":
+                val = fmt_bytes(cur)
+                rng = f"  [{fmt_bytes(min(data))}-{fmt_bytes(max(data))}]" if len(data) > 1 else ""
+            else:
+                val = fmt_count_rate(cur)
+                rng = f"  [peak {fmt_count_rate(max(data))}]" if data else ""
+            self.query_one(f"#label-{key}", Static).update(f"{label}: [b]{val}[/b][dim]{rng}[/dim]")
+            self.query_one(f"#spark-{key}", Sparkline).data = data or [0]
+
+    def render_system(self) -> None:
+        sm = self.snapshot.system if self.snapshot else None
+        w = self.query_one("#system", Static)
+        if not sm:
+            w.update("[dim]system counters disabled[/dim]")
+            return
+        t = Table.grid(padding=(0, 1))
+        t.add_column(style="dim")
+        t.add_column(justify="right")
+        t.add_column(style="dim")
+        rows = [
+            ("Available", sm.available, "free + reclaimable cache"),
+            ("Modified" if WINDOWS else "Dirty", sm.modified, "waiting to be written"),
+            ("Standby" if WINDOWS else "Page cache", sm.standby if WINDOWS else sm.cached, "cached file data"),
+            ("Kernel paged" if WINDOWS else "Slab reclaim", sm.kernel_paged, ""),
+            ("Kernel nonpaged" if WINDOWS else "Slab unreclaim", sm.kernel_nonpaged, "can't be paged out"),
+            ("Compressed", sm.compressed, "compression store" if WINDOWS else "zswap pool"),
+        ]
+        rows += [(k, v, "") for k, v in sm.extra.items()]
+        for label, value, note in rows:
+            if value is not None:
+                t.add_row(label, fmt_bytes(value), note)
+        w.update(Group(Text("System", style="bold"), t))
+
+    def _ordered(self, procs: list[ProcessMem]) -> list[ProcessMem]:
+        if self.grouped:
+            procs = group_by_app(procs)
+        return sort_procs(procs, self.sort_key)
+
+    def _row_key(self, p: ProcessMem) -> str:
+        return f"g:{p.name.lower()}" if self.grouped else f"p:{p.pid}:{p.create_time}"
+
+    def render_table(self) -> None:
+        t = self.query_one("#procs", DataTable)
+        procs = self._ordered(self.snapshot.processes)
+        if not self.show_all:
+            procs = procs[:TOP_N]
+        if self.selected and not any(self._row_key(p) == self.selected for p in procs):
+            # Keep the selected process visible even when it drops out of the top N.
+            sel = next((p for p in self._ordered(self.snapshot.processes) if self._row_key(p) == self.selected), None)
+            if sel:
+                procs.append(sel)
+        scroll_y = t.scroll_y
+        t.clear()
+        self.rows = {}
+        for p in procs:
+            k = self._row_key(p)
+            self.rows[k] = p
+            growth = Text(fmt_rate(p.growth_ps), justify="right")
+            if p.growth_ps and p.growth_ps > 1024 * 1024:
+                growth.stylize("bold red")
+            elif p.growth_ps and p.growth_ps > 64 * 1024:
+                growth.stylize("yellow")
+            elif p.growth_ps and p.growth_ps < -64 * 1024:
+                growth.stylize("green")
+            extra = (p.paged_pool or 0) + (p.nonpaged_pool or 0) if WINDOWS and p.paged_pool is not None else p.swapped
+            rt = f"{p.runtime or ''} {p.runtime_detail or ''}".strip()
+            cells = [
+                Text(f"×{p.count}" if self.grouped else str(p.pid), justify="right"),
+                p.name,
+                Text(fmt_bytes(p.resident), justify="right"),
+            ]
+            if LINUX:
+                cells.append(Text(fmt_bytes(p.pss), justify="right"))
+            t.add_row(
+                *cells,
+                Text(fmt_bytes(p.private), justify="right"),
+                growth,
+                Text(fmt_count_rate(p.faults_ps), justify="right"),
+                Text(fmt_bytes(extra) if extra is not None else "-", justify="right"),
+                Text(rt, style="magenta" if p.runtime else ""),
+                key=k,
+            )
+        if self.selected in self.rows:
+            t.move_cursor(row=t.get_row_index(self.selected), animate=False, scroll=False)
+        t.scroll_to(y=scroll_y, animate=False)
+
+    # ------------------------------------------------------------------ inspector
+    def on_data_table_row_highlighted(self, event: DataTable.RowHighlighted) -> None:
+        t = event.data_table
+        key = event.row_key.value if event.row_key else None
+        # Ignore stale events from clear()/rebuild: only the row under the cursor counts.
+        try:
+            current = t.coordinate_to_cell_key(t.cursor_coordinate).row_key.value
+        except Exception:  # noqa: BLE001 - empty table
+            return
+        if key != current or key == self.selected:
+            return
+        self.selected = key
+        self.query_one("#inspect-body", Static).update(Text(f"Inspecting {self.rows[key].name} …", style="dim"))
+        self._inspect_selected()
+
+    def _inspect_selected(self) -> None:
+        if not self.selected or not self.snapshot:
+            return
+        p = self.rows.get(self.selected)
+        if p is None:
+            return
+        if self.grouped:
+            members = [q for q in self.snapshot.processes if q.name.lower() == p.name.lower()]
+            if not members:
+                return
+            target = max(members, key=lambda q: q.resident)
+        else:
+            target = p
+        self.last_inspect = time.monotonic()
+        self.inspect_worker(target, p.count)
+
+    @work(thread=True, exclusive=True, group="inspect")
+    def inspect_worker(self, p: ProcessMem, group_count: int) -> None:
+        ins = self.collector.inspect(p)
+        self.call_from_thread(self.show_inspection, ins, group_count)
+
+    def show_inspection(self, ins: Inspection, group_count: int = 1) -> None:
+        self.inspection = ins
+        parts: list = []
+        head = Text()
+        head.append(f"{ins.name}", style="bold")
+        head.append(f"  pid {ins.pid}", style="dim")
+        if group_count > 1:
+            head.append(f"  (largest of {group_count})", style="dim")
+        parts.append(head)
+        if ins.error:
+            parts.append(Text(ins.error, style="red"))
+        if ins.categories:
+            total_res = sum(c.resident or 0 for c in ins.categories) or 1
+            t = Table(box=None, padding=(0, 1), show_edge=False, header_style="bold dim")
+            t.add_column("What", no_wrap=True)
+            t.add_column("Mapped", justify="right")
+            t.add_column("Resident", justify="right")
+            t.add_column("Shared", justify="right")
+            t.add_column("", width=8, no_wrap=True)
+            for c in ins.categories:
+                share = (c.resident or 0) / total_res
+                bar = Text("█" * max(0, round(share * 8)), style=C_USED)
+                t.add_row(c.name, fmt_bytes(c.mapped), fmt_bytes(c.resident), fmt_bytes(c.resident_shared), bar)
+            if ins.reserved:
+                t.add_row(Text("Reserved only", style="dim"), Text(fmt_bytes(ins.reserved), style="dim"), "", "", "")
+            parts.append(t)
+        if ins.top_files:
+            parts.append(Text("\nLargest file-backed pages", style="bold"))
+            ft = Table(box=None, padding=(0, 1), show_edge=False, show_header=False)
+            ft.add_column(justify="right")
+            ft.add_column(no_wrap=True, overflow="ellipsis")
+            for f in ins.top_files:
+                pp = PureWindowsPath(f.path)
+                label = Text(pp.name)
+                parent = str(pp.parent)
+                label.append("  " + (parent if len(parent) <= 30 else "…" + parent[-29:]), style="dim")
+                ft.add_row(fmt_bytes(f.resident if f.resident is not None else f.mapped), label)
+            parts.append(ft)
+        if ins.evidence:
+            parts.append(Text("\nEvidence", style="bold"))
+            for level, text in ins.evidence:
+                line = Text()
+                line.append(f"{level:<10}", style=LEVEL_STYLE.get(level, ""))
+                line.append(text)
+                parts.append(line)
+        if ins.cmdline:
+            parts.append(Text("\n" + " ".join(ins.cmdline)[:300], style="dim"))
+        parts.append(Text(f"\ninspected in {ins.elapsed * 1000:.0f} ms, refreshes every {INSPECT_EVERY:.0f}s", style="dim"))
+        self.query_one("#inspect-body", Static).update(Group(*parts))
+
+    # ------------------------------------------------------------------ actions
+    def _refresh_now(self) -> None:
+        if self.snapshot:
+            self.render_top()
+            self.render_table()
+
+    def action_sort(self) -> None:
+        self.sort_key = self.sort_keys[(self.sort_keys.index(self.sort_key) + 1) % len(self.sort_keys)]
+        self.notify(f"sort: {self.sort_key}", timeout=1.5)
+        self._refresh_now()
+
+    def action_group(self) -> None:
+        self.grouped = not self.grouped
+        self.selected = None
+        self._setup_columns()
+        self._refresh_now()
+
+    def action_toggle_all(self) -> None:
+        self.show_all = not self.show_all
+        self._refresh_now()
+
+    def action_charts(self) -> None:
+        self.chart_mode = self.chart_mode + 1 if self.chart_mode + 1 < len(CHARTS) else -1
+        self.query_one("#charts").set_class(self.chart_mode >= 0, "single")
+        self.render_charts()
+
+    def action_mode(self) -> None:
+        self.screen.toggle_class("slim")
+
+    def action_pause(self) -> None:
+        self.paused = not self.paused
+        self._refresh_now()
+
+    def action_help(self) -> None:
+        self.push_screen(HelpScreen())
+
+    def on_unmount(self) -> None:
+        self.collector.close()

memtaskman/cli.py

@@ -0,0 +1,135 @@
+"""Command-line entry point: `memtaskman` / `mtm`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+
+from memtaskman import __version__
+
+
+def _snapshot(args, collector=None):
+    from memtaskman.collector import Collector, sort_procs
+
+    c = collector or Collector(system=not args.no_system)
+    c.sample()
+    time.sleep(args.interval)
+    snap = c.sample()
+    top = sort_procs(snap.processes, "resident")
+    c.resolve_runtimes(top[:40], time_budget=2.0)
+    c.refresh_pss(top if args.all else top[: args.top], time_budget=2.0)
+    snap = c.sample()
+    return c, snap
+
+
+def cmd_main(args) -> int:
+    if args.once or args.json:
+        from memtaskman import report
+
+        c, snap = _snapshot(args)
+        c.close()
+        if not args.all:
+            snap.processes = sorted(snap.processes, key=lambda p: p.resident, reverse=True)[: args.top]
+        print(report.to_json(snap) if args.json else report.render_text(snap, top=None))
+        return 0
+    from memtaskman.app import MemTaskManApp
+
+    MemTaskManApp(interval=args.interval, system=not args.no_system).run()
+    return 0
+
+
+def cmd_inspect(args) -> int:
+    import psutil
+
+    from memtaskman import report
+    from memtaskman.collector import Collector
+
+    c = Collector(system=False)
+    snap = c.sample()
+    p = next((p for p in snap.processes if p.pid == args.pid), None)
+    if p is None:
+        try:
+            psutil.Process(args.pid)
+            print(f"pid {args.pid}: access denied", file=sys.stderr)
+        except psutil.NoSuchProcess:
+            print(f"pid {args.pid}: no such process", file=sys.stderr)
+        return 1
+    ins = c.inspect(p)
+    print(report.to_json(ins) if args.json else report.render_inspection(ins))
+    return 0 if not ins.error else 2
+
+
+def cmd_diff(args) -> int:
+    from memtaskman.diff import diff_snapshots
+
+    with open(args.a, encoding="utf-8") as fa, open(args.b, encoding="utf-8") as fb:
+        a, b = json.load(fa), json.load(fb)
+    print(diff_snapshots(a, b, top=args.top))
+    return 0
+
+
+def cmd_record(args) -> int:
+    from memtaskman.collector import Collector
+
+    c = Collector(system=not args.no_system)
+    c.sample()
+    n = 0
+    try:
+        with open(args.out, "a", encoding="utf-8") as f:
+            while args.count == 0 or n < args.count:
+                time.sleep(args.interval)
+                snap = c.sample()
+                if not args.all:
+                    snap.processes = sorted(snap.processes, key=lambda p: p.resident, reverse=True)[: args.top]
+                f.write(json.dumps(snap.to_dict(), separators=(",", ":")) + "\n")
+                f.flush()
+                n += 1
+                print(f"\rrecorded {n} snapshot(s) to {args.out}", end="", file=sys.stderr)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        c.close()
+        print(file=sys.stderr)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="memtaskman", description="An htop for what's inside your RAM, not just how full it is.")
+    p.add_argument("--version", action="version", version=f"memtaskman {__version__}")
+    p.add_argument("-i", "--interval", type=float, default=1.0, help="sample interval in seconds (default 1)")
+    p.add_argument("--once", action="store_true", help="print one text report and exit")
+    p.add_argument("--json", action="store_true", help="print one JSON snapshot and exit")
+    p.add_argument("--top", type=int, default=25, help="processes in --once/--json/record output (default 25)")
+    p.add_argument("--all", action="store_true", help="include every process in --once/--json/record output")
+    p.add_argument("--no-system", action="store_true", help="skip system-wide counters")
+    sub = p.add_subparsers(dest="cmd")
+
+    ins = sub.add_parser("inspect", help="break down one process's address space")
+    ins.add_argument("pid", type=int)
+    ins.add_argument("--json", action="store_true")
+    ins.set_defaults(func=cmd_inspect)
+
+    d = sub.add_parser("diff", help="compare two --json snapshots")
+    d.add_argument("a")
+    d.add_argument("b")
+    d.add_argument("--top", type=int, default=20)
+    d.set_defaults(func=cmd_diff)
+
+    r = sub.add_parser("record", help="append snapshots to a JSON Lines file")
+    r.add_argument("out")
+    r.add_argument("-i", "--interval", type=float, default=5.0)
+    r.add_argument("-n", "--count", type=int, default=0, help="stop after N snapshots (0 = until Ctrl+C)")
+    r.add_argument("--top", type=int, default=50)
+    r.add_argument("--all", action="store_true")
+    r.add_argument("--no-system", action="store_true")
+    r.set_defaults(func=cmd_record)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if getattr(args, "func", None):
+        return args.func(args)
+    return cmd_main(args)