Backup & Restore Claude Code Configuration / Claude Code 配置备份与恢复

English

Overview

Creates a clean zip backup of ~/.claude/ with logs and ephemeral content stripped out. Secrets (API keys, tokens, passwords) in env blocks are automatically redacted to <YOUR_..._HERE> placeholders. A restore.sh script is bundled into the zip so the backup is self-contained — no Claude Code needed to restore.

What gets included

settings.json, keybindings.json, CLAUDE.md — core config files
projects/ — per-project settings and CLAUDE.md files
plugins/marketplaces/ — registered plugin marketplace URLs
plans/ — saved plans
tasks/ — task tracking
ide/ — IDE integration config
restore.sh — bundled restore script

What gets excluded (why)

history.jsonl, *.jsonl — chat logs (large, privacy-sensitive)
telemetry/ — telemetry data (auto-regenerated)
cache/, plugins/cache/ — caches (re-downloaded on next use)
sessions/, session-env/ — ephemeral session state
shell-snapshots/ — temporary shell output
file-history/ — file change tracking (auto-regenerated)
backups/ — previous backups (avoids recursive bloat)
.last-cleanup, .claude.json, settings.json.mimo, settings.json.qwen

Usage

bash ~/.claude/skills/backup-claude-config/scripts/backup.sh [output-path]

If no output path is given, defaults to ~/Desktop/claude-config-backup-YYYYMMDD-HHMMSS.zip.

Restore

unzip claude-config-backup-*.zip -d /tmp/restore && bash /tmp/restore/restore.sh

Safely backs up existing ~/.claude/ to ~/.claude.bak.<timestamp> if present
Errors clearly if Claude Code is running and locking the directory

Security

Any env entries ending with _TOKEN, _KEY, _SECRET, _PASSWORD, or _AUTH are replaced with <YOUR_..._HERE> placeholders in settings.json and settings.local.json.

中文

概述

将 ~/.claude/ 目录打包为干净的 zip 备份文件，自动剔除聊天记录和临时文件。 settings.json 中的密钥（API Key、Token 等）自动替换为占位符。备份包内置 restore.sh 还原脚本，无需安装 Claude Code 即可恢复。

包含内容

settings.json、keybindings.json、CLAUDE.md — 核心配置文件
projects/ — 各项目的独立设置和 CLAUDE.md
plugins/marketplaces/ — 已注册的插件市场地址
plans/ — 已保存的计划
tasks/ — 任务跟踪记录
ide/ — IDE 集成配置
restore.sh — 内置还原脚本

排除内容（原因）

history.jsonl、*.jsonl — 聊天记录（体积大，涉及隐私）
telemetry/ — 遥测数据（自动重新生成）
cache/、plugins/cache/ — 缓存（下次启动自动重建）
sessions/、session-env/ — 临时会话状态
shell-snapshots/ — 临时命令行快照
file-history/ — 文件变更记录（自动重建）
backups/ — 旧备份（避免递归膨胀）
.last-cleanup、.claude.json、settings.json.mimo、settings.json.qwen

使用方式

bash ~/.claude/skills/backup-claude-config/scripts/backup.sh [输出路径]

不指定路径则默认保存到 ~/Desktop/claude-config-backup-年月日-时分秒.zip。

恢复方式

unzip claude-config-backup-*.zip -d /tmp/restore && bash /tmp/restore/restore.sh

如 ~/.claude/ 已存在，自动备份到 ~/.claude.bak.<时间戳> 后再覆盖
如果 Claude Code 正在运行导致目录被锁定，会明确报错并退出

安全保障

settings.json 和 settings.local.json 中所有以 _TOKEN、_KEY、_SECRET、 _PASSWORD、_AUTH 结尾的环境变量值，均替换为 <YOUR_..._HERE> 占位符。