Issue Station
Sign In
Tools hereToolbox

claude-code - ✅(Solved) Fix Claude Desktop macOS accumulates orphaned Claude Code backend processes during active use [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#45507•Fetched 2026-04-09 08:03:49
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
devan-borsboomdevan-borsboom
Participants
devan-borsboomdevan-borsboomRouteStylistRouteStylist
Timeline (top)
labeled ×5commented ×1

Claude Desktop on macOS spawns a new Claude Code backend process each time a Code mode conversation is started or switched, but does not terminate previous processes. These accumulate indefinitely, consuming significant RAM on memory-constrained machines.

Root Cause

Claude Desktop on macOS spawns a new Claude Code backend process each time a Code mode conversation is started or switched, but does not terminate previous processes. These accumulate indefinitely, consuming significant RAM on memory-constrained machines.

PR fix notes

PR #47830: feat: add subagent-cleanup plugin to terminate orphaned processes

Description (problem / solution / changelog)

Summary

  • Adds a subagent-cleanup plugin that terminates orphaned subagent processes (claude --resume) at session start
  • Prevents CPU/memory leaks from accumulating across sessions
  • Protects the current session's process chain by walking the parent PID tree

Problem

When using the Agent tool (Explore, Plan subagents), child processes are spawned via claude --resume. These are not always cleaned up when the parent session exits. Over multiple sessions, this leads to dozens or hundreds of orphaned processes:

$ ps aux | grep 'claude.*--resume' | wc -l
97

Each process consumes ~10% CPU and ~60-200MB RAM. On laptops this causes thermal throttling within minutes.

Solution

A SessionStart hook runs a Python script that:

  1. Lists all running claude --resume processes
  2. Walks the current PID's parent chain to build a protected set
  3. Sends SIGTERM to all unprotected subagent processes
  4. Reports cleanup count to stderr

The plugin approach is more precise than a simple pkill because it protects the active session chain and any concurrent sessions.

Test plan

  • Start a session, spawn multiple agents, exit
  • Start a new session with plugin enabled
  • Verify orphaned processes are cleaned up
  • Verify current session and its subagents still work

Fixes #47827

Relates to #20369, #33947, #46787, #45507, #33979

Changed files

  • plugins/README.md (modified, +1/-0)
  • plugins/subagent-cleanup/.claude-plugin/plugin.json (added, +8/-0)
  • plugins/subagent-cleanup/README.md (added, +76/-0)
  • plugins/subagent-cleanup/hooks/cleanup.py (added, +101/-0)
  • plugins/subagent-cleanup/hooks/hooks.json (added, +16/-0)
RAW_BUFFERClick to expand / collapse

Summary

Claude Desktop on macOS spawns a new Claude Code backend process each time a Code mode conversation is started or switched, but does not terminate previous processes. These accumulate indefinitely, consuming significant RAM on memory-constrained machines.

Environment

  • macOS 15 (Sequoia), Apple M3 Pro, 18 GB RAM
  • Claude Desktop 1.1348.0
  • Claude Code 2.1.92 (embedded in Desktop)

Reproduction

  1. Open Claude Desktop, enter Code mode
  2. Start a conversation, interact normally
  3. Start a new conversation (or switch away from the current one)
  4. Repeat 4-5 times over ~2 hours
  5. Run ps aux | grep "claude-code/.*claude.app" in Terminal

Observed

After 2.5 hours and ~5 conversation switches, 6 Claude Code backend processes were running. Only 1 was actively in use. The 5 stale processes consumed ~477 MB combined (~95 MB each).

PIDStartedRSSState
26642:56 PM79 MBStale
27362:57 PM106 MBStale
33873:23 PM96 MBStale (had --resume flag)
39124:01 PM93 MBStale
41424:12 PM103 MBStale
54005:20 PM247 MBActive

All processes: no TTY (??), identical flags (--output-format stream-json, --permission-mode bypassPermissions), same plugin directories. Each had a corresponding disclaimer wrapper process.

Expected

When a Code mode conversation is closed or replaced, the previous backend process should be terminated.

Impact

On an 18 GB machine, an 8-hour workday could waste 2-4 GB in orphaned processes. This directly contributed to severe memory pressure (17/18 GB used, 617 MB swap) observed before a forced restart.

Related Issues

  • #19201 -- Desktop macOS leaves orphaned CLI processes after quitting
  • #33947 -- MCP/subagent processes not cleaned up (107 orphans, ~7.75 GB)
  • #33979 -- Feature request for session manager with process lifecycle
  • #1935 -- MCP servers not terminated on exit (original report, June 2025)
  • #40706 -- Orphaned child process at 100% CPU for 29 hours

Note

This is specifically about processes accumulating during active Desktop use (conversation switching), not only after quitting the app. The Desktop app was still running and functional throughout.

extent analysis

TL;DR

The issue can be mitigated by implementing a process termination mechanism when a Code mode conversation is closed or replaced, ensuring that previous backend processes are properly cleaned up.

Guidance

  • Investigate the conversation switching logic to identify why previous backend processes are not being terminated.
  • Review the related issues (#19201, #33947, #33979, #1935, #40706) to see if there are any common patterns or solutions that can be applied to this problem.
  • Consider implementing a session manager with process lifecycle management (as suggested in #33979) to handle the creation and termination of backend processes.
  • Verify that the disclaimer wrapper process is properly cleaning up after the backend process, and that there are no other dependencies or resources that are preventing the process from being terminated.

Example

No specific code snippet can be provided without more information about the implementation, but a potential solution could involve adding a terminate or cleanup method to the conversation switching logic that properly shuts down the previous backend process.

Notes

The issue is specific to the accumulation of processes during active Desktop use, and not just after quitting the app. The solution will need to take into account the active use case and ensure that processes are properly cleaned up when conversations are switched or closed.

Recommendation

Apply a workaround by implementing a process termination mechanism, as this will help mitigate the issue of accumulating processes and reduce memory pressure. This can be done by investigating the conversation switching logic and implementing a session manager with process lifecycle management.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#network issue#logging issue#authentication issue#prompt issue#agent setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING