auto-manager

English | 简体中文

Claude Code 插件自动管理器

自动管理 Claude Code 插件的安装和更新，支持跨机器同步配置。

✨ 功能特性

• ✅ OS 级启动服务：macOS LaunchAgent / Linux systemd，彻底绕开 Claude Code settings 浅合并问题
• ✅ 自动安装：启动时自动安装快照中缺失的插件
• ✅ 智能重试：安装失败自动重试，10 分钟间隔，最多 5 次
• ✅ 自动更新：可配置每次启动更新或定时更新（默认：每次启动时更新）
• ✅ Marketplace 逐个更新：自动读取所有已知 marketplace 并逐个更新
• ✅ Git 同步：快照自动同步到 GitHub，支持多机器共享
• ✅ 仓库自同步：启动时自动 git pull 拉取最新快照和配置
• ✅ 自注册机制：启动时及插件操作后自动注册，防止 installed_plugins.json 被重建导致 Hook 丢失
• ✅ 全局 Hook：将 Hook 注册到 ~/.claude/settings.local.json，不依赖 installed_plugins.json，从根本上解决 Hook 丢失问题
• ✅ 全局规则同步：自动同步 global-rules/CLAUDE.md 到 ~/.claude/CLAUDE.md
• ✅ 全局 Skills 同步：自动同步 global-skills/ 目录到 ~/.claude/skills/
• ✅ 跨平台通知：更新完成后发送系统通知（macOS/Linux/Windows）
• ✅ 后台执行：不阻塞 Claude 启动
• ✅ 日志管理：自动轮转，最多保留 10MB
• ✅ 一键安装：新机器上运行一个脚本即可完成配置
• ✅ 跨平台支持：macOS、Linux、Windows、DevContainer

🚀 快速开始

🤖 方式一：Claude AI 助手一键设置（推荐）

最简单的方式：在新机器上启动 Claude Code 后，直接告诉 Claude：

"用 git@github.com:hyhmrright/claude-plugins-snapshot.git 设置我的插件"

Claude 会自动执行：

1. ✅ 克隆仓库到 ~/.claude/plugins/auto-manager
2. ✅ 运行安装脚本
3. ✅ 验证设置成功
4. ✅ 提示您重启 Claude Code

完全自动化，无需手动操作！ 🎉

---

🛠️ 方式二：手动安装

macOS / Linux / DevContainer

# 1. 克隆仓库到 Claude 插件目录
cd ~/.claude/plugins/
git clone git@github.com:hyhmrright/claude-plugins-snapshot.git auto-manager

# 2. 运行安装脚本（推荐使用 Python 版本）
cd auto-manager
python3 install.py

# 或使用 Bash 脚本（仅 Unix 系统）
# ./install.sh

# 3. 重启 Claude Code
# 插件会自动安装快照中的所有插件

Windows

# 1. 克隆仓库到 Claude 插件目录
# 注意：Windows 上 Claude 配置目录可能在 %APPDATA%\Claude
cd %USERPROFILE%\.claude\plugins
git clone git@github.com:hyhmrright/claude-plugins-snapshot.git auto-manager

# 2. 运行 Python 安装脚本
cd auto-manager
python install.py

# 3. 重启 Claude Code
# 插件会自动安装快照中的所有插件

就这么简单！🎉

首次设置（当前机器）

当前机器已完成设置，快照已同步到 GitHub。

📋 工作原理

自动化流程

OS 启动服务（登录时，主要机制）

每次用户登录时（macOS LaunchAgent / Linux systemd）：

• 等待 30 秒系统就绪，然后运行 auto-manager.py
• 完全独立于 Claude Code，不受 settings 文件配置影响
• 若服务文件缺失，auto-manager.py 下次运行时自动重建（自愈）

SessionStart Hook（会话启动时，辅助机制）

每次启动 Claude 时：

1. 备份清理：自动删除 Claude Code 生成的 ~/.claude.json.backup.<timestamp> 临时备份文件
2. 自注册检查：确保 auto-manager 在 installed_plugins.json 中注册（防止插件级 Hook 丢失）
3. 全局 Hook 检查：确保 Hook 在 ~/.claude/settings.local.json 中注册，并自动修正 matcher/async/timeout 字段
4. 仓库自同步：git pull 拉取最新快照和配置（在加载配置前执行，确保使用远程最新版本）
5. Marketplace 同步：将快照中的 marketplace 同步到本地 known_marketplaces.json（支持跨机器新增 marketplace）
6. 安装缺失插件：对比快照和当前安装，自动安装缺失的插件
   • 智能重试：安装失败后 10 分钟自动重试，最多 5 次
   • 状态记录：跟踪每个插件的安装状态和重试次数
7. 全局规则同步：自动同步 global-rules/CLAUDE.md 到 ~/.claude/CLAUDE.md
8. 全局 Skills 同步：自动同步 global-skills/ 目录到 ~/.claude/skills/
9. 自动更新（可配置）：
   • 默认行为（interval_hours: 0）：每次启动都更新 Marketplaces 和所有插件，确保始终最新
   • 定时更新（interval_hours: 24）：每 24 小时更新一次 Marketplaces 和插件
   • 更新顺序：先逐个更新 Marketplaces（从 known_marketplaces.json 读取），再逐个更新插件
   • 会话检测：在 Claude Code 会话中自动跳过更新（避免嵌套会话错误）
10. 智能同步：
    • ✅ 插件列表变化（安装/卸载）→ 生成快照并推送到 Git
    • ❌ 只是版本更新（自动更新）→ 不推送，避免无意义的 commit
11. 日志管理：

• 自动轮转，最多保留 10MB
• 超出时保留最近 8MB 内容

Git 同步策略

只在以下情况推送到 GitHub：

• ✅ 启动时检测到插件列表变化（安装/卸载）
• ✅ 启动时自动安装了缺失的插件
• ❌ 自动更新（只更新版本号，不改变插件列表）

这样可以避免每天产生大量无意义的 Git commit。

手动安装/卸载插件后的同步

如果在当前会话中安装/卸载了插件，有两种方式同步：

1. 重启 Claude Code（推荐）：SessionStart hook 会自动检测并同步
2. 手动运行同步命令（如需立即同步）：

   cd ~/.claude/plugins/auto-manager && python3 scripts/sync-snapshot.py
   

📁 目录结构

auto-manager/
├── .claude-plugin/
│   └── plugin.json          # 插件元数据
├── hooks/
│   └── hooks.json           # SessionStart Hook 配置（插件级，备选）
├── scripts/
│   ├── session-start.sh     # Hook 入口（async:true 由 Claude Code 负责后台化）
│   ├── session-start.py     # Hook 入口备选（Windows）
│   ├── startup-service.py   # OS 启动服务管理（macOS LaunchAgent / Linux systemd / cron）
│   ├── auto-manager.py      # 主逻辑（安装 + 更新）
│   ├── create-snapshot.py   # 生成插件快照
│   ├── git-sync.py          # Git 同步脚本
│   ├── sync-snapshot.sh     # 手动同步快照到 Git
│   └── sync-snapshot.py     # 手动同步快照（跨平台）
├── global-rules/            # 全局规则（Git 追踪，同步到 ~/.claude/CLAUDE.md）
│   └── CLAUDE.md
├── global-skills/           # 全局 Skills（Git 追踪，同步到 ~/.claude/skills/）
│   └── sync-snapshot/
│       └── SKILL.md
├── tests/                   # 测试用例（pytest）
│   ├── test_auto_manager.py
│   └── test_startup_service.py
├── snapshots/
│   ├── current.json         # 当前快照（唯一快照文件）
│   ├── .last-update         # 上次更新时间戳（本地）
│   └── .last-install-state.json  # 安装状态（本地）
├── logs/                    # 运行日志（本地）
│   └── auto-manager.log
├── config.json              # 配置文件
├── install.py               # 新机器安装脚本（推荐，跨平台）
├── install.sh               # 新机器安装脚本（仅 Unix）
├── .gitignore              # Git 忽略文件
└── README.md               # 本文档

🔧 常用命令

📦 插件同步到 Git

自动同步（推荐）

SessionStart Hook 会在每次启动 Claude Code 时自动检测插件变化并同步：