Memory headroom and parked agent processes

Agents: claude, codex, opencode · On: phone, desktop

Every agent runs inside VCode's cgroup. When the box gets close to its memory cap, new tabs are refused and idle agent processes are stopped so their tabs can be woken again on the next message.

Why you would use it

An idle claude tab holds about 480 MB with its MCP servers. Enough tabs and the machine runs into its cap, which on this box once meant a frozen desktop and a power cycle. This is what keeps that from happening while you are opening tabs from a phone.

How to use it

Nothing to do, except read the refusal when it comes.

Open tabs as usual.
Within 2 GiB of the cap, a new tab, an adopted session and a reopened tab are all refused.
Close a tab, or wait: idle tabs park themselves under pressure.

What you see

Creating a tab near the cap fails, and the toast carries the server's words with the request in front of them, such as memory 14.2 of 16.0 GB used: close a tab first. An adopted session and a reopened tab are refused the same way.

A red toast with the memory message inside it.

A parked tab looks no different. The next message you send takes a few seconds longer while the agent starts and the session is resumed, and the server log says parked <thread> after 4 min idle.

Options and settings

Thing	Value	What it changes
New-tab headroom	2 GiB	Below this much free, tabs cannot be created, adopted or reopened
Parking headroom	6 GiB	Below this much free, idle tabs start parking
Idle before parking	2 minutes	How long a tab must be quiet first
Reaper interval	60 seconds	How often the check runs
CPU quiet mark	2 seconds of CPU per minute	Above this, the tab is treated as working and left alone

The memory read is the cgroup's memory.current minus its reclaimable page cache (inactive_file), so a build that read a few gigabytes of files is not mistaken for a few gigabytes of live agents.

Limits and known gaps

Nothing parks while there is headroom, however long a tab has been idle. Parking is a pressure valve, not housekeeping.
A tab is never parked while a turn is running, while anything is queued, while a subagent is running, or while the adapter reports background work — a background Bash or Agent task, a scheduled wakeup that has not fired, or a cron job the agent registered. A wakeup keeps the process for two minutes past its time.
An adapter that cannot report background work at all is never parked.
A process tree burning CPU is not parked whatever the frames said. Work waiting on the network burns nothing, so that case still rests on the adapter's own account.
A tab seen for the first time is not parked on that tick: there is no CPU baseline to compare against yet.
Outside a cgroup with a cap — a dev run, or a unit that masks /sys/fs/cgroup — the guard reads as no limit and nothing is refused or parked.
Only claude tabs park. park() refuses unless the adapter reports backgroundBusy === false, and claude is the only adapter that reports it, so codex and opencode tabs are never stopped by the reaper.
Parking ends the tab's MCP servers too, so an open Playwright page does not survive it.
opencode parks itself separately: its acp process stops after ten minutes idle, whatever the memory pressure.