🌏 中文版
TL;DR
When you run several AI coding agent sessions side by side, the usual slowdown isn't the model. It's what the sessions leave behind: dev servers, test workers, Playwright MCP and the browsers it launches. Once the program that started them exits, they get adopted by the system (their PPID becomes 1) and nobody ever stops them. macOS gives you no way to cap a single process's memory, so the fix is three layers: reap what a session started when it exits normally, periodically reap orphans nobody owns, and alert when memory is about to run out.
Context
I usually keep several Claude Code sessions open, each working in its own git worktree on the backend or frontend. One day a pytest run had been going for 25 minutes but had used only 1.5 minutes of CPU. The rest of the time it was waiting on memory paging.
The problem
sysctl vm.swapusage showed 29.6 GB of swap in use out of 30.7 GB. The memory wasn't going to the agents I was actually using, but to processes nobody was using:
- 4 vite dev servers, up for more than a day, whose sessions had long since ended
- uvicorn and celery from another worktree, hanging off a session that had been open and resumed for two days
- 3 playwright-mcp processes, the oldest two days old; with its browsers it held about 3.5 GB
After all of that was stopped, swap usage dropped from 21 GB to 9 GB and the stuck tests started moving again.
Check whether it's orphan processes
These three commands tell you within a minute:
# How much swap is in use (macOS)
sysctl vm.swapusage
# Biggest memory users (includes compressed memory, more accurate than ps RSS)
top -l 1 -o mem -n 10 -stats pid,mem,command
# Dev services whose parent is already launchd (PPID=1): these are the orphans
ps -axo pid,ppid,etime,command | awk '$2 == 1' | grep -E 'uvicorn|celery|vite|vitest|pytest|playwright-mcp'
The etime column is how long a process has been running. A dev server that's been up for hours with a parent of 1 is almost certainly unused.
Why orphans get left behind
Simplified: launchd was always there; it is drawn in the agent's old spot for comparison.
There are four causes, and they stack:
- Children don't die with their parent. POSIX says that when a process exits, its children are adopted by a system process (
_exit()); on macOS that's launchd. An agent's tool shell is usually not the terminal's controlling process, so the children don't even get SIGHUP. They just keep running. - The way agents start servers is designed to detach. In
nohup uvicorn ... > log 2>&1 &, the&returns immediately,nohupblocks SIGHUP, and addingsetsidmoves the process into a new group so a group kill misses it. When users reported this on the Cursor forum, staff first asked whether the command used these forms. - Stopping only kills the outer layer. Node's
subprocess.kill()only kills the direct child; the official example says the process inside the shell is not terminated. For nested commands likenpm run dev→vite→esbuildorpytest→ xdist workers, stopping the shell leaves everything underneath running. - One set of MCP servers per session. The MCP spec makes the client responsible for shutting down stdio servers, and only as a SHOULD. Every session starts its own MCP servers, so parallel sessions multiply the process count. A measurement post found that in two of three sessions, the MCP servers used more memory than Claude Code itself.
Claude Code adds one more amplifier: a foreground command that hits its timeout is moved to the background instead of being stopped. A stuck pytest goes from living for one tool call to living for the whole session, and becomes an orphan if the session ends abnormally.
You're not the only one
Every major tool has public reports, and most aren't fully fixed (status as of 2026-11):
| Tool | Representative report | Status |
|---|---|---|
| Claude Code | #95821: after an MCP connect timeout the spawned process is never killed; 5 sessions accumulated 373 orphans | Open |
| Claude Code | #96625: after a crash or force-quit, background processes are adopted by launchd and keep running | Open |
| Codex CLI | #30408: each thread starts its own MCP set and never reaps it; about 9.3 GB after 25 threads | Open |
| Cursor | Forum: staff confirm background terminal processes don't shut down when a session ends | Known issue |
| Cline | #14622: in hub mode MCP servers are never stopped; 10 Serena instances after a day and a half | Open |
| Playwright MCP | Claude Code #78551: old browsers not reaped after reconnecting; about 13 GB over 3 days | Closed (not planned) |
There's also a cautionary tale in the other direction. A comment on Claude Code #96625 notes that Codex 0.97–0.98 once killed background jobs at the end of every turn, which broke legitimate long-running nohup jobs and watch loops. Tools can't just kill everything, which is part of why this has dragged on.
What the official mechanisms cover
Claude Code actually cleans up well on a normal exit. The docs say:
Background tasks are automatically cleaned up when Claude Code exits. On macOS and Linux, when you stop a background task from
/tasksor Claude Code stops it at exit, processes that detached from the task's shell, such as ones started undersetsidortimeout, stop too.
The gaps are everything outside that guarantee:
- Crash, kill, or closing the terminal. The SessionEnd hook reasons are only
clear,resume,logout,prompt_input_exitandother; the docs don't promise it fires on an abnormal exit. - SessionEnd gets very little time. The default total budget is 1.5 seconds; raise it with a per-hook
timeoutorCLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS. - Background sessions hand their processes on. When the supervisor reaps an idle session, its background shells carry over to the next process; they only stop when you delete the session.
CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1makes them stop with the process. - The memory cap is Linux-only.
CLAUDE_CODE_TOOL_MEMORY_LIMITis built on cgroups and supports only Linux and WSL.
Codex has /ps and /stop to list and stop background terminals; Cursor's sessionEnd hook is fire-and-forget. None of the three guarantees cleanup after an abnormal exit.
Why macOS can't cap memory
On Linux, the most complete answer is to wrap the whole session in a cgroup (covered below). macOS has no cgroups, and the things that look like they should work don't:
ulimitdoesn't work. On macOS 26,ulimit -mreturns "bad option" andulimit -vreturns "setrlimit failed". Thesetrlimit(2)man page says that when memory is tight, "the system will prefer to take memory from processes that are exceeding their declared resident set size". That's a reclaim preference, not a limit. launchd'sResidentSetSizeuses the same wording.- Swap has no fixed ceiling. Apple's virtual memory documentation says swap "uses all of the available space on the machine's boot partition". Idle pages of orphan processes keep getting swapped out; the system doesn't crash, it just gets slower.
- The OS won't kill much for you either. A comment in the XNU source says macOS has only "a very limited jetsam that is only invoked under extreme conditions", i.e. when swap or compressor space is nearly exhausted.
The only real hard cap on macOS is a container: Docker --memory, or the Docker Desktop VM limit.
My setup: three layers
Every single layer has holes, so I use three, each covering what the previous one misses:
| Layer | When it acts | Catches | Misses |
|---|---|---|---|
| 1. SessionEnd hook | Session exits normally | Dev servers and tests this session started | Crash, kill, sessions that never close |
| 2. Periodic reaper | Every 5 minutes | Orphans with PPID 1, long-running Playwright MCP | Services under a session that's still alive |
| 3. Memory gate | Continuously | Pauses the newest test run when tests exceed the cap; alerts when swap is nearly full | Doesn't kill anything itself; a human decides |
Layer 1: a SessionEnd hook reaps what this session started
The hook walks up from itself to this session's claude process and reaps every matching process tree beneath it. Two details matter: take the process snapshot as soon as the hook starts (once claude exits its children get re-parented to launchd and the tree is gone), and fork into the background before killing so the 1.5-second budget doesn't cut it off.
MATCH = re.compile(
r"(^|[/\s])pytest(\s|$)|-m pytest|vue-tsc"
r"|(^|[/\s])uvicorn\s|(^|[/\s])celery\s.*\bworker\b|manage\.py\s+runserver"
r"|vite(\.js)?\s|vitest|pnpm\s+(dev|vite)\b|npm\s+run\s+dev\b"
)
# 1. snapshot: ps -axo pid=,ppid=,comm=,command=
# 2. walk up to the ancestor whose comm == "claude"
# 3. walk down collecting MATCH processes and their descendants
# 4. fork + setsid to detach, send SIGTERM (plus SIGCONT to wake paused ones), SIGKILL survivors after 5 s
Register the script under hooks.SessionEnd in ~/.claude/settings.json. The pattern only lists dev services, so MCP servers aren't hit by mistake.
Layer 2: launchd reaps orphans every 5 minutes
A LaunchAgent (StartInterval 300) runs a scanner with two rules:
- uvicorn, celery worker, runserver, vite, vitest or
pnpm devwhose parent is already 1 and that have run longer than 4 hours: nobody owns them, reap the whole tree. - Playwright MCP, whatever its parent, reaped after 12 hours. It often hangs off sessions that never close, and its browser tabs keep piling up.
ps -axo pid=,ppid=,etime=,command= | while read -r pid ppid etime cmd; do
[ "$ppid" = 1 ] || continue
grep -Eq "$PATTERN" <<<"$cmd" || continue
grep -q 'mcp' <<<"$cmd" && continue
[ "$(etime_secs "$etime")" -ge "$orphan_secs" ] || continue
pids=$(tree "$pid" | tr '\n' ' ')
log "REAP pid=$pid age=$etime tree=[$pids]"
kill -TERM $pids; kill -CONT $pids
( sleep 10; kill -KILL $pids 2>/dev/null ) &
done
tree is a small function that recurses with pgrep -P. Give the script a DRY_RUN=1 mode that only lists what it would touch, and run it once before installing.
Layer 3: a memory gate
A separate resident watchdog sums the memory of every pytest and vue-tsc process tree every 5 seconds. Above half of physical RAM it sends SIGSTOP to the newest run (pausing, not killing) and resumes runs in order once usage drops. The layer-2 script also checks swap: at 80% or more it pops an osascript notification listing the top five memory users, at most once every 30 minutes.
Use top's MEM column rather than ps RSS: under memory pressure many pages are compressed or swapped out, and RSS badly underestimates.
A paused test looks exactly like a hung one. That's what fooled me this time: I assumed the tests had deadlocked until the log showed the gate had paused them. So log every pause and resume clearly.
Options on Linux and in containers
On Linux, systemd-run --user --scope with MemoryHigh and MemoryMax caps an entire agent session, and writing to cgroup.kill at the end takes down forked processes too, setsid or not:
systemd-run --user --scope -p MemoryHigh=6G -p MemoryMax=8G -p MemorySwapMax=0 -- claude
Be aware that when the OOM killer takes out an xdist worker, the whole test run can hang, so wrap test commands in timeout -k as well.
Containers (one per agent) work on both platforms, but the devcontainer hostRequirements.memory field is a minimum requirement, not a cap; to limit memory add --memory to runArgs.
Start fewer processes in the first place
Reaping is cleanup after the fact. These settings reduce what gets started:
- Give Playwright MCP an idle timeout.
--idle-timeoutdefaults to one hour for headless browsers and never for headed ones. To share one browser across agents, run it in HTTP mode with--shared-browser-context, at the cost of agents' tabs interfering with each other. - Size xdist workers by memory.
-n autolooks only at physical CPU cores, not memory. When several agents run tests at once, lower it withPYTEST_XDIST_AUTO_NUM_WORKERS. - Use run-once test commands.
vitest runinstead ofvitest,tscinstead oftsc --watch. Watch mode never exits by design. - celery on macOS doesn't reap its children when SIGKILLed. The official docs note that only Linux gets the
PR_SET_PDEATHSIGsafety net; on macOS youpkillthem yourself.
Limitations
- The reaper will kill services you left running on purpose. A dev server you started with
nohupand meant to keep gets reaped after 4 hours. The thresholds are environment variables; tune them. - Sessions that never close slip through. The service's parent is still alive, so layer 2 leaves it alone; only the swap alert reminds you to close it.
- launchd doesn't run while the Mac is asleep, so after waking it can take up to 5 minutes to catch up.
- There are community tools too: cc-reaper uses a Stop hook plus a LaunchAgent to reap Claude Code orphans with a similar approach, and is a good starting point to adapt.
What I learned
Most AI agent tools clean up well when they exit normally. What leaks is crashes, forced exits and sessions that never close, and the more sessions you run in parallel, the more leaks you get. macOS gives you no memory cap to set, so you need your own periodic orphan reaper plus an alert for when swap is about to fill.
References
- Claude Code: Background Bash commands (interactive mode)
- Claude Code: Hooks reference (SessionEnd)
- Claude Code: Agent view and the supervisor
- Claude Code issue #95821: MCP retries leak orphaned processes
- Claude Code issue #96625: background processes orphaned after a crash
- Claude Code issue #78551: Playwright MCP browsers accumulating
- OpenAI Codex issue #30408: per-thread MCP processes never cleaned up
- Codex CLI slash commands (/ps, /stop)
- Cursor forum: agent-started vite orphaned with PPID 1
- Cursor forum: possible memory leak with test command
- Cursor Hooks (sessionEnd)
- Cline issue #14622: hub-mode MCP servers never stopped
- Playwright MCP README (--idle-timeout, --shared-browser-context)
- MCP specification: Lifecycle › Shutdown
- Node.js child_process: subprocess.kill()
- POSIX _exit()
- GNU coreutils: nohup
- Apple: About the Virtual Memory System
- XNU source: kern_memorystatus.c
- systemd-run
- systemd.resource-control (MemoryHigh, MemoryMax)
- Linux cgroup v2 documentation
- pytest-xdist issue #658: hang after OOM kills a worker
- pytest-xdist: Distribution (-n auto)
- Docker: Resource constraints
- Dev Container JSON reference (hostRequirements)
- Celery: Stopping the worker
- John Young: Claude Code Memory Usage: How Many Sessions Fit on One Machine
- cc-reaper