Claude Code Using 20 GB RAM? Find the Runaway Child

If Claude Code climbs into double-digit gigabytes of memory, stop launching new subagents and identify the growing process before you restart, downgrade, or kill anything. Current reports show at least two different child-process signatures: long-running background research agents and a version-named Claude Code process executing embedded ugrep. They need different fixes, and the parent session may still be healthy.

Do not start with pkill claude, delete task history, disable permissions, or assume the newest version is the cause. First capture the parent PID, child PID, resident memory, and command line. That evidence tells you whether you can terminate one runaway child while preserving the main session.

Confirm Which Process Is Growing

On macOS, sample the largest processes with:

ps -axo pid=,ppid=,rss=,comm=,args= | sort -k3,3nr | head -20

On Linux, use:

ps -eo pid=,ppid=,rss=,comm=,args= --sort=-rss | head -20

Run the command two or three times about 30 seconds apart. RSS is reported in KiB, so a value of 1048576 is about 1 GiB. On macOS, compressed memory and the process footprint can make Activity Monitor disagree with RSS, but the repeated samples still reveal which PID is growing.

Interpret the result before acting:

The process name alone is not enough. One current Linux investigation initially classified a version-named process as a leaking subagent. The reporter later found that Claude Code's embedded ugrep was running under the versioned executable and consuming memory while compiling a regex. Check args before calling a process an agent.

Stop Fan-Out Before the Host Freezes

If the Claude Code interface still responds:

1. Tell the main session to stop starting subagents and cancel any unfinished research fan-out.

2. Record the growing PID, parent PID, RSS, and sanitized command line.

3. Ask the main session for a short recovery summary of completed work and pending tasks.

4. Stop the affected background task through Claude Code's normal controls.

5. Sample the process list again and confirm memory stopped growing.

This is safer than closing every Claude process. A broad kill can terminate unrelated sessions, MCP servers, and work that was not involved in the leak.

One August 8 macOS report described roughly ten concurrent background subagents, including eight research agents making repeated Bash, WebSearch, and WebFetch calls. Two child processes reached reported footprints of 26.4 GiB and 20.3 GiB while the machine became unresponsive. A separate Linux report recorded OOM kills at 14.5 GiB and 21.3 GiB. Those reports establish the severity, but they do not prove that every high-memory Claude session has the same cause.

Terminate Only the Confirmed Runaway PID

If the UI cannot stop the child and memory is still climbing, resolve the exact PID from the read-only sample above. Verify its parent and command again, then request a normal termination:

kill -TERM 12345

Replace 12345 with the confirmed runaway child PID. Check whether it exited:

ps -p 12345 -o pid=,ppid=,rss=,comm=,args

If the same PID remains and the host is close to freezing, a forceful termination of that exact child is the last local containment step:

kill -KILL 12345

Do not copy these commands until you have verified the PID. PIDs are reused, and terminating the wrong process can lose unrelated work. Never substitute pkill claude, killall claude, or a version-wide pattern when one child is the target.

After the child exits, confirm that the main session remains stable. If the parent also exits, use the recovery summary to start a fresh session rather than resuming the same unbounded fan-out immediately.

Check for the Embedded ugrep Signature

If the growing child's arguments contain ugrep, inspect the Bash command immediately before memory growth. The current issue thread documents a reproducible failure where an extended regex with multiple bounded repeats such as {0,16} caused compilation memory to rise on an empty input file. The Bash timeout did not reliably contain the detached child in that report.

For a confirmed match:

• stop the exact runaway PID;

• replace the search with Claude Code's built-in Grep tool;

• reduce the regex to one bounded region or a simpler sequence of searches; and

• if you deliberately choose an operating-system grep for one known text file, use its absolute path and recheck its syntax instead of assuming embedded ugrep flags are portable.

Do not install an unreviewed hook from an issue comment into ~/.claude/settings.json. A hook executes local code before tool calls and can silently broaden or block behavior. Keep this recovery narrow unless your team has reviewed, tested, and owns the guard.

Prevent the Next OOM

Retest with a bounded workload rather than the original full fan-out:

1. Update Claude Code through its supported installer and record the exact version.

2. Start one background agent, not the whole research set.

3. Give it a narrow source list and explicit result limit.

4. Keep large command output out of the conversation. Redirect diagnostics to a reviewed file, then read only the relevant slice.

5. Sample the parent and child RSS for several minutes.

6. Add one agent at a time only after the previous run stays flat.

Do not treat a rollback as a confirmed fix. The current reports disagree about version correlation, and one investigation reproduced the runaway across older and newer builds. A clean run after downgrading can also be a smaller workload or a trigger that did not fire.

Likewise, do not delete transcripts first. One macOS report found only 300-600 KB per subagent transcript and no individual tool result over 34 KB even though the process footprint was enormous. Preserve the evidence until you know whether the parent, an agent child, or a tool child grew.

Use Bounded Actions for Research-Heavy Work

Raw curl, broad filesystem scans, and full-page shell output give a research subagent more data to retain and make the triggering call harder to audit. For provider-backed research, use a structured Action with a small result limit and a preflighted cost instead.

Start with this exact setup phrase:

Follow https://aident.ai/SETUP.md

Then ask:

Check Aident Loadout authentication and Vault status. Search the staging capability catalog for the current read-only GitHub issue lookup and web-search Actions, inspect their schemas, and preflight exact lookups for anthropics/claude-code issues 84960 and 85015 plus one web search capped at 10 results. If the inputs are valid and the estimates are within 5 credits total, execute them and return only issue number, state, updated time, title, canonical URL, and ten short search-result summaries. Do not use Bash, start subagents, comment, react, edit, expose credentials, or return full page bodies.

The verification is measurable: the run uses reviewed read-only Actions, returns bounded structured fields, creates no GitHub write, and puts no provider token or multi-megabyte shell output into the conversation.

Set up Aident Loadout for bounded research.

Report the Reproduction Upstream

If memory still rises on a bounded current build, add evidence to the closest open issue instead of opening a title-only duplicate. Include:

• Claude Code version, install method, operating system, and available memory;

• parent and child PID relationships;

• three timestamped RSS or footprint samples;

• sanitized comm and args for the growing process;

• background-agent count and the tool call immediately before growth;

• whether the child was claude, a version-named executable, or ugrep; and

• whether stopping the exact child recovered the parent session.

Do not attach secrets, full environment dumps, private source, or raw session transcripts. A small, attributable process timeline is more useful than a giant diagnostic archive.

Sources

• Anthropic: Claude Code tools reference

• Anthropic Claude Code issue 84960: repeated Linux OOM kills

• Issue 84960 investigation: embedded ugrep process signature

• Anthropic Claude Code issue 85015: background agents freeze a 16 GB Mac

Refresh this guide when issues 84960 or 85015 close with a confirmed fix, Anthropic documents a child-process memory ceiling, or a release changes the embedded search process signature.