Skip to content

Add a Task Manager that shows how much RAM each session uses - #113

Open
vivi7 wants to merge 1 commit into
doctly:mainfrom
vivi7:feat/ram-task-manager
Open

vivi7 wants to merge 1 commit into
doctly:mainfrom
vivi7:feat/ram-task-manager

Conversation

@vivi7

@vivi7 vivi7 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a Task Manager to the sidebar's More menu, after the separator and right before Global settings. It lists every running session and task, heaviest first, with how much memory and CPU its whole process tree uses, and lets you end a single process inside a session or stop the session for good.

Why

With several sessions open, the machine can slow down and it is hard to tell which session is responsible. A session costs more than its CLI: MCP servers, dev servers, watchers and builds all run under it. Activity Monitor shows these as unrelated node, python or zsh processes, with no link back to the session that started them.

There is also a quieter leak. Stop hangs up the PTY. A child that ignores SIGHUP, or that runs in the background, outlives the session. It is reparented to launchd and keeps its memory, and nothing in the app shows it any more.

What it does

  • More → Task Manager opens a full-page viewer, like Stats and Global settings.
  • Summary cards: RAM of all sessions and tasks, with its share of installed memory; RAM and CPU of Switchboard's own Electron processes; how many sessions and processes are running.
  • A table sorted by RAM, one row per live session (Claude, Codex, terminal) and per running task. Each row shows the process count, CPU, RAM (with its share of installed memory and a bar relative to the heaviest row, amber above 1 GB, red above 2 GB) and uptime. The name and sub-line come from the sidebar's session data: the title, then kind, short project path and PID.
  • A row expands into its process tree, with the name, the full command line, PID, CPU and RAM of each process. Interpreters are named after their script, for example node cli.js instead of node.
  • Kill, on any process except the root, sends SIGTERM to that process only, and the session keeps running. Use it on a runaway dev server, for example. If the process is still there on the next refresh, the button becomes Force kill (SIGKILL).
  • Stop asks first, then stops the session or task the usual way. After a grace period it sends SIGTERM to whatever of the tree is still alive, and SIGKILL after a short wait. Nothing it started is left behind as an orphan. A process only gets a signal if it still has the PID and name it had when Stop was pressed, so a reused PID is never hit.
  • If a session is still listed after Stop, the row offers Force kill, which sends SIGKILL to the whole tree.
  • Open shows the session, or the task's log.
  • The viewer refreshes every 3 s (6 s on Windows) only while it is visible and the window is not hidden. It renders with morphdom, so scroll position and expanded rows survive each refresh.

Implementation notes

  • New process-monitor.js:
    • One process-table snapshot per refresh. On macOS and Linux it runs ps -A -o pid=,ppid=,rss=,pcpu=,stat=,comm= with LC_ALL=C; on Windows, Get-CimInstance Win32_Process (working set, no CPU).
    • Each owner is measured as the sum over its tree. Zombies are skipped and the tree walk is cycle-safe.
    • Full command lines are fetched only for the processes on screen.
    • killInTree refuses a PID that is not under the owner's root right now. killTree sends SIGKILL deepest first. stopTree handles the stop → SIGTERM → SIGKILL escalation.
  • main.js: four IPC handlers, get-process-usage, stop-owner, kill-owned-process and force-stop-owner. The renderer only sends an owner reference (session id, or task project path and label). Root PIDs are always resolved in main from activeSessions or the task manager, never taken from the renderer.
  • task-manager.js: listProcesses() returns the running, non-compound tasks that own a process.
  • preload.js: getProcessUsage, stopOwner, killOwnedProcess, forceStopOwner.
  • public/process-viewer.js (new) and #process-viewer in index.html. public/icons.js adds a memory icon (Lucide's memory-stick shape). public/app.js adds the menu entry. The other full-page viewers (grid, plans, memory, stats, settings) now also hide the Task Manager when they open.
  • public/style.css: a pm- section in the existing dark palette, with a narrow layout below 860 px.

Testing

  • New test/process-monitor.test.js (13 tests) covers:
    • parsing ps output (decimal comma, names with spaces, zombies left out) and the Windows output
    • tree walk order and cycle safety, tree totals, interpreter naming, kill order
    • measure sorting
    • the killInTree guard
    • killTree
    • stopTree escalation, including a clean stop that signals nothing and a reused PID that is never hit
  • test/task-manager.test.js: listProcesses lists only running tasks that own a process.
  • npm test: 566 tests, all pass except fileDiff reads tracked and untracked changes… and projectGitInfo and projectGitDiff…. Those two fail the same way on current main on my machine because of a global color.ui = always git setting. With color.ui=auto, 566/566 pass.
  • Manual check on macOS in the running app (electron . with an isolated SWITCHBOARD_DATA_DIR), with two terminals: one running a node process holding about 300 MB, the other a node process that ignores SIGHUP and SIGTERM.
    • The More menu reads Plans, Agent Files, Stats, separator, Task Manager, Global settings.
    • The heavy terminal was listed first (289 MB, 3 processes), then the other (54 MB).
    • Kill on the 300 MB node ended it and the terminal kept running.
    • Stop on the other terminal removed it, and its node child was gone too (checked with ps). Before this change, that child survived as an orphan.
    • No renderer errors.

Notes

  • RAM is resident memory (RSS), so memory shared between processes is counted once per process. The viewer says so in a footnote.
  • The Windows path (PowerShell snapshot, no CPU column) is not tested on Windows yet. For a WSL terminal, only the Windows-side process is visible.
  • The sidebar's own Stop is unchanged and still only hangs up the PTY. If you like the cleanup, I can switch it to the same stopTree in a follow-up.

More → Task Manager lists every running session and task, heaviest first,
with the memory, CPU and process count of its whole process tree: the CLI
plus its MCP servers, dev servers and builds. A row opens into its
processes, and each child can be killed on its own while the session goes
on.

Stop ends a session the usual way, then terminates whatever of its tree
outlived the hangup (SIGTERM, then SIGKILL), so a child that ignores
SIGHUP is not left behind as an invisible orphan. Pids are always resolved
in main from the session or task itself, and a kill only reaches a process
that is still in that tree.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant