AI导哈

进程清理插件

Process Guardian是一款自动清理Claude Code会话中孤儿进程的插件，适用于macOS、Linux和Windows系统。

  • by ibarapascal
  • Shell
  • 本地部署
  • 更新于
在 GitHub 查看 ibarapascal/process-guardian

使用说明

进程守护者

自动清理Claude Code会话中的孤立进程


概述

Claude Code插件，用于自动清理AI编码会话中的孤立进程。

问题：

  • 当运行多个代理或MCP服务器时，会出现意外退出——OOM终止、会话崩溃、启动失败
  • 这些进程留下了孤立进程，有些进程在后台默默地消耗了100%的CPU
  • 其他人会被忽视，直到你的机器冻结——手动清理很快就会过时

它的作用：

  • 会话启动时自动清理孤立的Claude子代理和MCP服务器（allowlist）
  • 跟踪Bash工具调用产生的进程，并清理崩溃会话中的孤立进程（会话跟踪）
  • 提供 /check 手动过程管理命令
  • 支持macOS、Linux和Windows

关键原则：

  • 两层防御：已知模式的allowlist+任意脚本的会话跟踪
  • Allowlist仅适用于已知进程，未知进程将被完全忽略
  • 会话跟踪捕获通过Bash工具生成的任何在崩溃后成为孤立的东西

安装

claude plugin marketplace add ibarapascal/process-guardian
claude plugin install process-guardian@process-guardian

就是这样。插件在每次会话开始时都会自动运行。

用法

自动（默认）

开始新的克劳德会议。流程监护人将：

  1. 会话跟踪：检查以前崩溃会话中的孤儿，并杀死经过验证的孤儿
  2. 允许列表扫描：扫描与已知模式匹配的孤立进程（ppid=1）并杀死它们
  3. 报告已清洁的内容（或友好的状态消息）

在您的会话期间， PostToolUse(Bash) 钩子默默地跟踪新的PPID=1个进程（每次Bash调用的开销约为50ms）。在干净退出时，跟踪数据标记为干净。在崩溃/Ctrl+C时，下一个会话会自动清理。

手册

/check

扫描并显示跟踪的会话进程和满列表匹配的孤立进程，并提供杀死特定进程的选项。

安全：仅允许列表

你的正常流程从未被触及。

方法 未知过程 风险
黑名单 可能被杀 高
允许名单 忽略 无

什么会被杀死

只有这些特定的模式：

  • claude --* （有争论的下属）
  • @modelcontextprotocol/server-*
  • @playwright/mcp, playwright-mcp
  • @upstash/context7-mcp
  • 浏览器与 --remote-debugging-port 或 ms-playwright

什么是安全的

  • 您的浏览器（Chrome、Firefox、Safari）
  • 您的Electron应用程序（VS Code、Slack、Discord）
  • 您的开发服务器（webpack、vite、next）
  • 一切都不是在对抗中

运作原理

第1层：允许列表扫描（SessionStart）

扫描PPID=1进程并杀死那些匹配已知模式的进程（Claude子代理、MCP服务器）。快速和确定性。

第2层：会话PID跟踪（PostToolUse→ 会话开始）

跟踪Bash工具调用产生的进程：

  1. 会话开始：快照当前PPID=1流程作为基线
  2. PostToolUse（Bash）：每次Bash调用后，与基线的差异→ 记录新孤儿
  3. 会话结束：标记 .clean 退出
  4. 下一个会话开始：碰撞（无 .clean) → 通过三重验证（PID+开始时间+命令）杀死被跟踪的孤儿

这捕获了allowlist无法覆盖的任意脚本（Python、Node等）。

平台支持

平台 允许列表扫描 会话跟踪
macOS ✅ ✅
Linux ✅ ✅
Windows ✅ — （尚未）

支持的MCP服务器

类别 示例
官方 @modelcontextprotocol/server-filesystem, server-memory, server-git, server-puppeteer, 更多。..
剧作家 @playwright/mcp, playwright-mcp, mcp-server-playwright
背景7 @upstash/context7-mcp
其他 @anthropic/claude-mcp, @composio/mcp, apidog-mcp-server

测试

要验证插件是否正常工作：

步骤1：创建孤立进程

# Method: Use a subshell that exits immediately, orphaning the child process
(npx @playwright/mcp &)

# Verify it's orphaned (ppid = 1)
ps -eo pid,ppid,command | awk '$2 == 1' | grep -E "playwright|mcp"

步骤2：测试清理

# Start a new Claude Code session
claude

# You should see:
# [Process Guardian] Cleaned 1 orphan process(es):
#   PID=xxxxx node .../npx/.../mcp...

或者跑 /check 手动扫描和管理孤立进程。

备选方案：现实世界场景

# Start Claude with MCP server, then force-kill the terminal
claude  # with Playwright MCP configured
# Force close terminal (Cmd+Q / kill -9 terminal PID)
# Reopen terminal, start new claude session - orphans should be cleaned

贡献

  1. 分叉存储库
  2. 添加图案 scripts/lib/patterns.sh
  3. 在您的平台上进行测试
  4. 提交拉取请求

所有投稿必须使用英语。

🤖 欢迎AI协助的贡献！ 欢迎使用Claude Code、GitHub Copilot或其他人工智能工具来帮助您做出贡献。

了解更多

许可证

麻省理工学院

专为Claude Code社区打造

报告Bug · 请求功能

相关 MCP