# Claude Vault

> Back up Claude Code account data and migrate it across machines and accounts. Use when the user wants to: back up ~/.claude; migrate conversation history, CLAUDE.md, skills, settings, and memory to a new machine or new account; or when `claude --resume` can't find / is missing past conversations (often because moving machines or non-ASCII / CJK project paths cause project-directory slug collisions). Cross-platform (macOS / Linux / Windows), Python stdlib only.

- Skill: `runesmith-studio/claude-vault` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add runesmith-studio/claude-vault`
- Raw SKILL.md: https://api.skillmd.com/api/skills/runesmith-studio/claude-vault/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Runesmith-Studio (https://skillmd.com/u/runesmith-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/runesmith-studio/claude-vault

---


# claude-vault — back up, recover, and re-home Claude Code account data

A cross-platform, zero-dependency tool that snapshots Claude Code's `~/.claude` and safely restores
conversation history and config to a new environment on a **machine move or account migration**.

## When to use

- "Back up my Claude account / my conversations"
- "I'm moving to a new account — how do I bring my history and config along?"
- "I switched computers, how do I migrate my conversation history?"
- "`claude --resume` can't find / no longer shows my past sessions"
- "Set up a daily automatic backup of Claude"

## Entry point

The script lives at `scripts/vault.py`. Run it with the system Python (3.8+; nothing to `pip install`):

```bash
python3 scripts/vault.py <subcommand> [options]
python3 scripts/vault.py --help        # overview
python3 scripts/vault.py status        # current snapshots + auto-backup status
```

> Symlink the repo into `~/.claude/skills/` to use it as a skill in any session; the script itself runs from anywhere.

## Machine / account migration: three steps

After the new account is signed in to Claude Code:

```bash
# 1) Preview first (dry-run by default — never touches ~/.claude)
python3 scripts/vault.py restore /path/to/claude-vault-XXXX.tar.zst

# 2) Check the on-screen summary and the manifest (~/.claude-vault/manifests/), then apply
python3 scripts/vault.py restore /path/to/claude-vault-XXXX.tar.zst --apply

# 3) Restart Claude Code; `claude --resume` should now list the history
```

Restore automatically:
- **Protects the new login** — does not write `.credentials.json`, and keeps the new machine's account
  fields in `.claude.json` (`oauthAccount` / `userID`), so it won't break the new login or re-link the old account.
- **Remaps across machines** — after moving machine / username, it recomputes each session's project-dir
  slug from the real `cwd` recorded inside the session, rewriting that `cwd` when needed so `claude --resume` finds it.
- **Is reversible** — auto-creates a "pre-restore snapshot" before applying.

## Daily: enable automatic backup

```bash
python3 scripts/vault.py backup                 # snapshot now
python3 scripts/vault.py schedule --time 03:00  # daily at 03:00 (macOS launchd / Linux cron)
python3 scripts/vault.py schedule --uninstall   # turn it off
```

Snapshots go to `~/.claude-vault/snapshots/`, keep the newest 14, and **exclude login credentials by default** (no tokens shipped to git/cloud).

## Sessions "lost" without a machine move: re-home

Non-ASCII project paths often collapse several directories into one slug, so `claude --resume` mixes them up or loses them. Fix it without any backup:

```bash
python3 scripts/vault.py rehome            # dry-run: list what would move where
python3 scripts/vault.py rehome --apply    # apply after review
```

## Subcommand cheat sheet

| Subcommand | Purpose | Safe defaults |
|---|---|---|
| `backup` | Pack `~/.claude` into a snapshot | no credentials; keep newest 14 |
| `restore` | Restore from a snapshot to a new machine / account | dry-run; protects login; auto pre-restore snapshot |
| `rehome` | Re-file mislocated sessions by real cwd | dry-run; writes a manifest |
| `status` | Show snapshot & auto-backup status | read-only |
| `schedule` | Install / remove daily auto-backup | — |

## Safety guarantees (remember these)

- `restore` and `rehome` are **dry-run by default** — they only print a plan + write a manifest; `--apply` performs it.
- `restore --apply` snapshots the current `~/.claude` first, so it's reversible.
- Backup and restore **never touch login credentials by default**; only `backup --include-credentials` (same account, same user, just a new machine) includes them.
- Every change is written to a manifest under `~/.claude-vault/manifests/` for line-by-line auditing.
- **Migrates content, not access**: this moves content/account-state files to a new account/machine; it does NOT restore access to an account you can't sign into (sign in with a working account first). Snapshots contain your data — keep the `.tar.*` files private.

## How it works, in one line

Claude stores each conversation as `~/.claude/projects/<slug>/<id>.jsonl`, where `<slug>` is the working
directory with every non-`[A-Za-z0-9]` character (including `/` and CJK) replaced by `-`. Moving machines or
using non-ASCII paths makes the slug mismatch or collide, so sessions become "unfindable" — the tool repairs
this using the real `cwd` recorded inside each session. See `README.md` and `scripts/vault.py --help` for details.