Issue Station
Sign In
Tools hereToolbox

claude-code - ✅(Solved) Fix Subagent processes not cleaned up after session ends [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#47827•Fetched 2026-04-15 06:41:11
View on GitHub
Comments
1
Participants
2
Timeline
8
Reactions
1
Author
hmennen90hmennen90
Participants
github-actions[bot]github-actions[bot]hmennen90hmennen90
Timeline (top)
labeled ×4cross-referenced ×2commented ×1referenced ×1

When using the Agent tool extensively (e.g., Explore, Plan subagents), the spawned subagent processes are not reliably cleaned up after they complete or when the parent session ends. Over multiple sessions, this leads to dozens or even hundreds of orphaned claude --resume processes accumulating.

Root Cause

When using the Agent tool extensively (e.g., Explore, Plan subagents), the spawned subagent processes are not reliably cleaned up after they complete or when the parent session ends. Over multiple sessions, this leads to dozens or even hundreds of orphaned claude --resume processes accumulating.

Fix Action

Workaround

Adding a SessionStart hook to settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pkill -f 'claude.*--resume' 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

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)

Code Example

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pkill -f 'claude.*--resume' 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}
RAW_BUFFERClick to expand / collapse

Description

When using the Agent tool extensively (e.g., Explore, Plan subagents), the spawned subagent processes are not reliably cleaned up after they complete or when the parent session ends. Over multiple sessions, this leads to dozens or even hundreds of orphaned claude --resume processes accumulating.

Reproduction

  1. Start a Claude Code session
  2. Use Agent tool multiple times (Explore, Plan, etc.)
  3. End the session
  4. Start new sessions and repeat
  5. Run ps aux | grep 'claude.*--resume' | wc -l

After a day of normal usage, I had 97 orphaned subagent processes consuming significant CPU and memory.

Impact

  • High CPU usage from zombie processes (each process consumes ~10% CPU)
  • Memory pressure (each process ~60-200MB RSS)
  • On laptops: contributes to thermal throttling
  • Users may not notice until system becomes sluggish

Expected Behavior

Subagent processes should be terminated when:

  • The subagent task completes and results are returned
  • The parent session ends
  • The parent session is interrupted

Workaround

Adding a SessionStart hook to settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pkill -f 'claude.*--resume' 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

Environment

  • Claude Code: latest (installed via npm)
  • macOS 26.4.1 (Apple Silicon + Intel)
  • Heavy Agent tool usage (Explore, Plan subagents)

extent analysis

TL;DR

Implementing a SessionStart hook with a command to kill orphaned claude --resume processes can mitigate the issue of accumulating zombie processes.

Guidance

  • Verify the issue by running ps aux | grep 'claude.*--resume' | wc -l after multiple sessions to check for orphaned processes.
  • Apply the provided workaround by adding a SessionStart hook to settings.json to kill orphaned processes at the start of each session.
  • Monitor CPU usage and memory pressure after applying the workaround to ensure it effectively mitigates the issue.
  • Consider exploring additional solutions to prevent orphaned processes from accumulating in the first place, rather than just mitigating the symptoms.

Example

The provided workaround code snippet can be used as an example:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pkill -f 'claude.*--resume' 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  }
}

This code kills any processes matching the pattern claude.*--resume at the start of each session.

Notes

This workaround may not be a permanent solution and may need to be combined with other fixes to fully resolve the issue. The root cause of the orphaned processes is not addressed by this workaround.

Recommendation

Apply the workaround by adding the SessionStart hook to settings.json, as it provides a temporary solution to mitigate the issue of accumulating zombie processes.

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…
#configuration error#environment variable#network issue#logging issue#authentication issue

Still need to ship something?

×6

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

Back to top recommendations

TRENDING