Skip to content

About

Back up every Claude Code and Cowork session to a local markdown vault, and resume any project from any account

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

7 Commits

Folders and files

Repository files navigation

Claude-Backup β€” Back up every Claude session, resume from any account

MIT license macOS, Windows and Linux PowerShell 5.1+ Bash CI status Last commit GitHub stars

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

Why Claude-Backup?

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:

  1. 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).
  2. 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.

Features

πŸ—„οΈ Everything, organised by project

  • Full conversation transcripts from ~/.claude/projects/, converted from JSONL to readable markdown
  • Plans, prompt history, session metadata and file edit history, grouped by the project they belong to
  • Cowork transcripts and output files, plus your CLAUDE.md, settings, hooks and plugins

⏯️ Resume from any account

  • Say "pick up where I left off" or "resume my-web-app" in a new session
  • Loads only the project you name (or the one matching your working directory), not the whole vault
  • Warns you when the last successful backup is more than 24 hours old

🏷️ Plans you can actually find

  • Random plan names like binary-singing-lake.md are renamed from the plan's own heading
  • A plans/_index.md per project: topic and a one-line summary for every plan
  • "list plans", "show me plans for X" and "resume [plan name]" just work

πŸ” Incremental and safe to re-run

  • Skips files whose modification time hasn't changed (.timestamps.json)
  • Marks each run IN PROGRESS first, so a backup that died halfway is visible
  • Never deletes or overwrites with less data; failures are logged and the run continues

πŸ” Search and health checks

  • vault-search: find past decisions, code and prompts across every project at once
  • vault-verify: last backup time, missing files, stale-vault warnings at 12, 24 and 72 hours

πŸ”’ Private by default

  • The vault is plain markdown on your own disk; the installers only copy files, and nothing syncs unless you set it up
  • A .gitignore in the vault keeps transcripts, file history and shell snapshots out of any repo you sync it to
  • One-line installers for macOS, Windows and Linux, with --check and --uninstall

Tech stack

PowerShell Bash Markdown Claude Skills

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.

Architecture

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
Loading

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.

Quick start

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.ps1 contains 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.

Run the first backup

  1. Open Claude Desktop in Cowork mode.
  2. Go to Scheduled in the sidebar.
  3. Click Run now on session-backup, and allow access to ~/.claude and ~/Documents when asked.

That's it. Your first backup populates the vault; after that the task is meant to run every 6 hours.

Make the resume skill available

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-resume folder and upload it as a custom skill in Claude's settings.

Resume a project

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.

Optional skills

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.

What gets backed up

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

Configuration

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.

Security

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).

How it works

What each backup run does
  1. Marks the run IN PROGRESS in _backup-log.md, then reads all Claude Code data from ~/.claude/
  2. Builds a project path map from history.jsonl to decode the encoded directory names
  3. Groups everything by project and converts JSONL transcripts to readable markdown
  4. Classifies plan files by reading their full content and matching them to projects
  5. Renames plan files from random codenames (e.g. binary-singing-lake.md) to descriptive titles from the plan's heading
  6. Captures active Cowork session transcripts and output files via the session API
  7. Generates per-project summaries with "Quick Resume" sections
  8. Runs incrementally, skipping unchanged files using stored modification times
  9. Builds a master index linking everything together
  10. Logs the run to _backup-log.md as SUCCESS or PARTIAL

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).

Troubleshooting

Backup ran but the vault is empty
  • Check that Cowork directory access was granted when the task ran (~/.claude and ~/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.jsonl has 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.md for 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* or linux*, open install.sh and 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-Backup folder (cd Claude-Backup first)

Requirements

  • Claude Desktop with Cowork mode
  • Claude Code (for Code session backups)
  • macOS, Linux, or Windows (PowerShell 5.1+)

Project structure

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

Docs

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

Roadmap

  • Make install.ps1 parse 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-search and vault-verify with 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.md and settings back into ~/.claude on a new machine

Contributing

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.

License

MIT Β© 2026 Abhinav Das

Star history

Star history chart


Built by Abhinav Das

If this project helped you, consider giving it a ⭐

About

Back up every Claude Code and Cowork session to a local markdown vault, and resume any project from any account

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages