Never lose your Claude context again. Every session, plan and prompt backed up to a local markdown vault, and any new session β on any account β picks up where you left off.
Features Β· Quick start Β· Architecture Β· Docs Β· Roadmap Β· Contributing
Claude accounts log you out. Sessions expire. Context disappears. You're left scrambling to remember what you were working on, which decisions were made, and where you left off.
Claude-Backup is two things:
- A scheduled backup that runs every 6 hours as a Cowork task, archiving your Claude Code sessions, Cowork
transcripts, implementation plans, prompt history, file edits and config into a structured local vault
(
~/Documents/ClaudeVault/by default). - A resume skill,
vault-resume, that any new Claude session can use to read the vault and pick up exactly where you left off, regardless of which account you're on.
Restoring here means restoring context: nothing is written back into ~/.claude. A fresh session reads the vault
and carries on.
|
|
|
|
|
|
There is no backup binary: the backup is a Cowork scheduled task whose instructions live in
scheduled-task/SKILL.md, and Claude carries them out. The installers only put the task
and the resume skill in place, with your vault path filled in.
flowchart LR
subgraph SRC["~/.claude on your machine"]
P["projects/*.jsonl (Code, Cowork and Desktop conversations)"]
PL["plans/*.md"]
H["history.jsonl"]
S["sessions/*.json"]
FH["file-history/"]
G["CLAUDE.md, settings.json, plugins/"]
SS["shell-snapshots/"]
end
API["Cowork session API (list_sessions, read_transcript)"]
TASK["session-backup: Cowork scheduled task, every 6 h"]
subgraph VAULT["ClaudeVault (markdown)"]
IDX["_index.md, _backup-log.md"]
PRJ["projects/name/: summary, plans, transcripts, history"]
CW["cowork/id/: transcript, files"]
GL["_global/: CLAUDE.md, settings, hooks, plugins"]
end
subgraph SKILLS["Skills in any new session"]
R["vault-resume"]
SE["vault-search"]
V["vault-verify"]
end
P & PL & H & S & FH & G & SS --> TASK
API --> TASK
TASK --> IDX & PRJ & CW & GL
R & SE & V -- "read" --> VAULT
history.jsonl is the ground truth for which project each conversation belongs to: every entry carries the project's
real absolute path, so the task builds a path map before decoding the encoded directory names under
~/.claude/projects/. See docs/ARCHITECTURE.md for the full backup pipeline, the vault format
and how the skills read it.
You need: Claude Desktop with Cowork, and git. For Claude Code session backups, Claude Code. Pick your OS:
π macOS
git clone https://github.com/abhinav-adtechs/Claude-Backup.git
cd Claude-Backup
chmod +x install.sh
./install.sh # vault in ~/Documents/ClaudeVault
./install.sh ~/Dropbox/ClaudeVault # β¦or anywhere you like| What | Installed to |
|---|---|
| Resume skill | ~/.claude/vault-resume/SKILL.md |
| Scheduled task | ~/Documents/Claude/Scheduled/session-backup/SKILL.md |
| Default vault | ~/Documents/ClaudeVault/ (gets a .gitignore) |
./install.sh --check # verify the installation
./install.sh --uninstall # remove the skill and the task; the vault is keptπͺ Windows
Run it from PowerShell 7 (pwsh) or from Windows PowerShell 5.1, which is built into Windows 10 and 11.
git clone https://github.com/abhinav-adtechs/Claude-Backup.git
cd Claude-Backup
.\install.ps1 # vault in Documents\ClaudeVault
.\install.ps1 -VaultPath "C:\Users\you\Dropbox\ClaudeVault" # β¦or anywhere you like| What | Installed to |
|---|---|
| Resume skill | %USERPROFILE%\.claude\vault-resume\SKILL.md |
| Scheduled task | %USERPROFILE%\Documents\Claude\Scheduled\session-backup\SKILL.md |
| Default vault | %USERPROFILE%\Documents\ClaudeVault\ (gets a .gitignore) |
.\install.ps1 -Check # verify the installation
.\install.ps1 -Uninstall # remove the skill and the task; the vault is kept[!TIP] If PowerShell says running scripts is disabled on this system, allow it for the current window only, then run the installer again:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
[!NOTE] Windows PowerShell 5.1 reads scripts saved without a byte-order mark in the system code page, and
install.ps1contains a few non-ASCII characters. If 5.1 reports a parse error, run the installer with PowerShell 7 instead:pwsh -File .\install.ps1. The installer writes the vault path with forward slashes inside the skills (C:/Users/you/...), which is expected.
π§ Linux
git clone https://github.com/abhinav-adtechs/Claude-Backup.git
cd Claude-Backup
chmod +x install.sh
./install.sh # vault in ~/.local/share/ClaudeVault
./install.sh /path/to/vault # β¦or anywhere you like| What | Installed to |
|---|---|
| Resume skill | ~/.claude/vault-resume/SKILL.md |
| Scheduled task | ~/.local/share/claude/Scheduled/session-backup/SKILL.md |
| Default vault | ~/.local/share/ClaudeVault/ (gets a .gitignore) |
./install.sh --check and ./install.sh --uninstall work the same as on macOS.
Important
Run the installer from inside the cloned Claude-Backup folder: it reads skill/, scheduled-task/ and
vault-gitignore.template relative to the current directory.
- Open Claude Desktop in Cowork mode.
- Go to Scheduled in the sidebar.
- Click Run now on
session-backup, and allow access to~/.claudeand~/Documentswhen asked.
That's it. Your first backup populates the vault; after that the task is meant to run every 6 hours.
The installer writes vault-resume, with your vault path filled in, to ~/.claude/vault-resume/SKILL.md. Add that
folder to Claude the way you add any custom skill:
-
Claude Code: copy it into your personal skills folder.
mkdir -p ~/.claude/skills && cp -R ~/.claude/vault-resume ~/.claude/skills/
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\skills" | Out-Null Copy-Item -Recurse "$env:USERPROFILE\.claude\vault-resume" "$env:USERPROFILE\.claude\skills\"
-
Claude Desktop: zip the
vault-resumefolder and upload it as a custom skill in Claude's settings.
In any new Claude session (Code, Cowork or Chat), just say:
- "Pick up where I left off"
- "What was I working on?"
- "Resume [project name]"
- "What's the status of my projects?"
vault-resume reads your vault and gives you the context back: the last prompts you sent, architectural decisions,
current bugs and suggested next steps. Name a project and only that project is loaded; ask generally and you get a
summary across all projects from _index.md. It also follows the conventions in your backed-up _global/CLAUDE.md.
| Skill | Ask it | What it does |
|---|---|---|
vault-search |
"search my vault for X", "find where I decided X", "did I ever work on Y" | Searches plans, summaries, history, then transcripts; groups hits by project |
vault-verify |
"check my vault", "verify backup", "is my backup up to date" | Reports the last backup time, missing files and incomplete projects as a health report |
The installers don't install these two. Add the skill-search and skill-verify folders the same way as the resume
skill. They read the default vault path, so if you installed to a custom location, replace ~/Documents/ClaudeVault/
in their SKILL.md first.
| Data | Source | Location in the vault |
|---|---|---|
| Full conversation transcripts | ~/.claude/projects/ |
projects/<name>/transcripts/ |
| Implementation plans | ~/.claude/plans/ |
projects/<name>/plans/ |
| Prompt history | ~/.claude/history.jsonl |
projects/<name>/history.md |
| Session metadata | ~/.claude/sessions/ |
projects/<name>/sessions/ |
| File edit history | ~/.claude/file-history/ |
projects/<name>/file-history/ |
| Global config | ~/.claude/CLAUDE.md |
_global/CLAUDE.md |
| Settings and hooks | ~/.claude/settings.json |
_global/settings-snapshot.md |
| Installed plugins | ~/.claude/plugins/ |
_global/plugins.md |
| Cowork transcripts | ~/.claude/projects/ + session API |
cowork/<id>/transcript.md |
| Cowork output files | Cowork working dirs | cowork/<id>/files/ |
| Shell environment | ~/.claude/shell-snapshots/ |
shell-snapshots/ |
Everything is organised by project, with generated summaries and a master index.
Vault structure
~/Documents/ClaudeVault/
βββ _index.md # Master index with Quick Resume per project
βββ _backup-log.md # When backups ran
βββ _global/ # Your Claude config, hooks, plugins
βββ projects/
β βββ my-web-app/
β β βββ _project-summary.md # Overview + Quick Resume
β β βββ plans/ # Implementation plans (renamed to descriptive titles)
β β β βββ _index.md # Table of all plans with topics and summaries
β β β βββ *.md # Individual plan files
β β βββ transcripts/ # Full conversation transcripts
β β βββ sessions/ # Session metadata
β β βββ history.md # Every prompt you sent
β β βββ file-history/ # Files Claude edited
β βββ _unmatched/ # Plans not tied to a project
βββ cowork/
β βββ _cowork-index.md
β βββ <session-id>/
β βββ transcript.md
β βββ files/
βββ shell-snapshots/ # Terminal environment
There are no environment variables or config files: the installers take everything as arguments.
| Option | macOS / Linux | Windows |
|---|---|---|
| Install, default vault | ./install.sh |
.\install.ps1 |
| Install, custom vault | ./install.sh /path/to/vault |
.\install.ps1 -VaultPath C:\path |
| Check the installation | ./install.sh --check |
.\install.ps1 -Check |
| Uninstall (keeps vault) | ./install.sh --uninstall |
.\install.ps1 -Uninstall |
Change the vault location by installing again with the new path. Dropbox, iCloud Drive or an external drive work
well for redundancy. If the vault is outside ~/Documents, make sure Cowork can reach that folder too.
Change the backup frequency in the task's schedule in Cowork. Every 6 hours is 0 */6 * * *; some alternatives:
| Schedule | Cron |
|---|---|
| Every hour | 0 * * * * |
| Every 12 hours | 0 */12 * * * |
| Once a day, at midnight | 0 0 * * * |
Back up right now: Cowork βΊ Scheduled βΊ Run now on session-backup.
Warning
The vault contains your full conversation history, which may include API keys, passwords or proprietary code you shared during sessions. Never sync it to a public repository.
The installer creates a .gitignore in the vault (from vault-gitignore.template) the
first time, so if you sync the vault to a git repo or a cloud service, the sensitive parts stay out:
| Excluded | Why |
|---|---|
projects/*/transcripts/, cowork/*/transcript.md, cowork/*/files/ |
May contain credentials or sensitive data |
projects/*/file-history/ |
May contain proprietary source code |
shell-snapshots/ |
May contain exported environment variables |
.timestamps.json |
Incremental backup state |
Plans, summaries and history are considered safe to sync. For extra protection, keep the vault on an encrypted volume (an encrypted disk image on macOS, or a VeraCrypt volume on Windows or Linux).
What each backup run does
- Marks the run
IN PROGRESSin_backup-log.md, then reads all Claude Code data from~/.claude/ - Builds a project path map from
history.jsonlto decode the encoded directory names - Groups everything by project and converts JSONL transcripts to readable markdown
- Classifies plan files by reading their full content and matching them to projects
- Renames plan files from random codenames (e.g.
binary-singing-lake.md) to descriptive titles from the plan's heading - Captures active Cowork session transcripts and output files via the session API
- Generates per-project summaries with "Quick Resume" sections
- Runs incrementally, skipping unchanged files using stored modification times
- Builds a master index linking everything together
- Logs the run to
_backup-log.mdasSUCCESSorPARTIAL
The resume skill teaches Claude how to navigate the vault: which files to read first, how to scope context to the relevant project, and how to respect your coding conventions.
How path encoding works
Claude Code stores conversation files under ~/.claude/projects/ in directories named by encoding the project's
absolute path: each / becomes -. For example, /Users/alice/WebKitchen/my-app is stored as
-Users-alice-WebKitchen-my-app.
That is ambiguous when a directory name contains a dash. Claude-Backup uses history.jsonl as ground truth, since
every history entry contains the real absolute path, and builds a map of known paths before decoding directory names.
Directories with no history entry fall back to probing the disk (a known gap with the leading dash and with
spaces in paths is on the roadmap).
Backup ran but the vault is empty
- Check that Cowork directory access was granted when the task ran (
~/.claudeand~/Documents) - Re-run the backup and watch for access request dialogs
A project is missing from the vault
- The project may have no history entries yet (a new project with no completed prompts)
- Check that
~/.claude/history.jsonlhas entries with the project's path:grep "/your/project" ~/.claude/history.jsonl
Plans show up in _unmatched/
- The plan file may not mention the project path or name
- Plans are classified by reading their full content; if the project context is ambiguous, they land in
_unmatched/ - Move them manually to the correct
projects/<name>/plans/directory
Last backup shows IN PROGRESS
- A previous backup did not complete
- Check
_backup-log.mdfor the timestamp: if it's more than 30 minutes old, the backup failed mid-run - Re-run the backup; it processes files incrementally
./install.sh fails with "Unsupported OS"
- Check your
$OSTYPE:echo $OSTYPE - If it's not
darwin*,linux-gnu*orlinux*, openinstall.shand add your variant to the Linux branch - On Windows, use
install.ps1
install.sh or install.ps1 can't find skill/SKILL.md
- Run the installer from inside the cloned
Claude-Backupfolder (cd Claude-Backupfirst)
- Claude Desktop with Cowork mode
- Claude Code (for Code session backups)
- macOS, Linux, or Windows (PowerShell 5.1+)
Claude-Backup/
βββ install.sh Installer for macOS and Linux (--check, --uninstall, custom vault path)
βββ install.ps1 Installer for Windows (-VaultPath, -Check, -Uninstall)
βββ scheduled-task/SKILL.md The session-backup Cowork task: the whole backup procedure
βββ skill/SKILL.md vault-resume: how a new session loads context from the vault
βββ skill-search/SKILL.md vault-search: search across the vault (optional)
βββ skill-verify/SKILL.md vault-verify: vault health report (optional)
βββ vault-gitignore.template Copied to <vault>/.gitignore on first install
βββ docs/ARCHITECTURE.md The backup pipeline, vault format and skills in depth
| Doc | What's in it |
|---|---|
| docs/ARCHITECTURE.md | The installers, the backup task step by step, the vault format, the skills |
| scheduled-task/SKILL.md | The backup procedure itself, as Claude reads it |
| CONTRIBUTING.md | Setup, testing changes safely, conventions, PR checklist |
| CHANGELOG.md | What changed in each release |
- Make
install.ps1parse and write BOM-less skill files in Windows PowerShell 5.1 - Install the skills where Claude Code discovers them (
~/.claude/skills/) - Let the installers run from any directory
- Install
vault-searchandvault-verifywith the vault path filled in - Decode project directories with spaces and the leading dash correctly
- A Windows install smoke test in CI
-
vault-restore: put plans,CLAUDE.mdand settings back into~/.claudeon a new machine
Issues and pull requests are welcome, especially from Windows and Linux users. See CONTRIBUTING.md
for how to test an installer or skill change without touching your real ~/.claude.
MIT Β© 2026 Abhinav Das
Built by Abhinav Das
If this project helped you, consider giving it a β