{
  "markdown": "<div align=\"center\">\n\n# claude-backup\n\n**Claude Code deletes your sessions after 30 days.**\n\n<p>\n  <a href=\"https://www.npmjs.com/package/claude-backup\"><img src=\"https://img.shields.io/npm/v/claude-backup.svg\" alt=\"npm version\"></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\"></a>\n  <img src=\"https://img.shields.io/badge/Platform-macOS-lightgrey.svg\" alt=\"macOS\">\n  <a href=\"https://github.com/tombelieber/claude-backup/stargazers\"><img src=\"https://img.shields.io/github/stars/tombelieber/claude-backup?style=social\" alt=\"GitHub stars\"></a>\n</p>\n\n</div>\n\n> [!IMPORTANT]\n> **The maintained `backup` agent skill now lives in\n> [Tomstack](https://github.com/tombelieber/tomstack/tree/main/skills/productivity/backup).**\n> Install and update the reusable skill from Tomstack. This repository remains\n> the supported home of the `claude-backup` CLI, scheduler, npm package,\n> standalone plugin, and runtime releases.\n\nEvery debugging session. Every architecture decision. Every prompt you spent an hour crafting. Gone.\n\nWhatsApp keeps your messages forever. Telegram keeps them forever. Discord keeps them forever. Claude Code — the tool you pay $20–200/mo for — gives you 30 days.\n\n<div align=\"center\">\n\n```bash\nnpx claude-backup\n```\n\n**One command. Your sessions are safe. Auto-syncs daily.**\n\n</div>\n\n---\n\n## What You're Losing\n\nClaude Code stores everything in `~/.claude/` — your settings, custom agents, hooks, skills, and **every conversation you've ever had**. Sessions older than 30 days? Silently deleted.\n\nEach session is:\n\n- A **debugging journal** — the exact steps that fixed that impossible bug\n- An **architecture record** — why you chose that pattern, with the AI's reasoning\n- A **prompt library** — the carefully worded instructions that actually worked\n- A **learning log** — mistakes, corrections, breakthroughs, all timestamped\n\nYou can't Google your own Claude sessions. Once they're gone, they're gone.\n\n---\n\n## How It Works\n\n```bash\nnpx claude-backup\n```\n\nInteractive setup:\n\n1. Checks requirements (git, gzip, python3)\n2. Creates a private GitHub repo (or local-only if you prefer)\n3. Backs up your config and all sessions (gzipped)\n4. Sets up automatic backups (configurable: daily, 6h, hourly)\n\nThat's it. Run it once, forget about it.\n\n---\n\n## Get Your Sessions Back\n\nBrowse and restore any session from your backups:\n\n```bash\n# List all backed-up sessions\nclaude-backup restore --list\n\n# Show the last 5 sessions\nclaude-backup restore --last 5\n\n# Filter by date\nclaude-backup restore --date 2026-02-27\n\n# Filter by project\nclaude-backup restore --project myproject\n\n# Restore a specific session\nclaude-backup restore <uuid>\n```\n\nThe session index is auto-generated on every sync and rebuilt from the `*.jsonl.gz` files — you never need to manage it manually.\n\n---\n\n## What Gets Saved\n\n**Config profile** — settings, CLAUDE.md, agents, hooks, skills, rules. Lightweight (< 100 KB), portable between machines.\n\n**Sessions archive** — all chat history, compressed with gzip. Your entire conversation history, safe in a private repo.\n\n<details>\n<summary><strong>Full backup manifest</strong></summary>\n<br>\n\n| Item | Source | Notes |\n| --- | --- | --- |\n| Settings | `settings.json` | Plugins, preferences |\n| Local settings | `settings.local.json` | Permission overrides |\n| User instructions | `CLAUDE.md` | User-level system prompt |\n| Custom agents | `agents/` | Agent definitions |\n| Custom hooks | `hooks/` | Automation scripts |\n| Custom skills | `skills/` | User-authored skills |\n| Custom rules | `rules/` | Custom rules |\n| Session files | `projects/**/*.jsonl` | Chat history (gzipped) |\n| Session indexes | `projects/**/sessions-index.json` | Session metadata |\n| Command history | `history.jsonl` | CLI command history (gzipped) |\n\nAll source paths are relative to `~/.claude/`.\n\n</details>\n\n---\n\n## Machine Migration\n\nYour config took hours to perfect. Move it in seconds.\n\n```bash\n# Old machine\nclaude-backup export-config\n# => ~/claude-config-2026-02-25.tar.gz (47 KB)\n\n# Transfer via AirDrop, USB, email, etc.\n\n# New machine\nnpx claude-backup import-config claude-config-2026-02-25.tar.gz\n```\n\nPlugins are not included in the export (they are re-downloaded on first launch). Only the plugin manifest in `settings.json` is backed up.\n\n---\n\n## Backend Modes\n\nChoose where your backups live:\n\n```bash\n# GitHub private repo (default if gh is installed)\nnpx claude-backup\n\n# Local only — no remote, no GitHub needed\nnpx claude-backup --local\n\n# Custom git remote\nnpx claude-backup --backend git\nclaude-backup backend set git --remote git@myserver:backups.git\n```\n\nSwitch backends anytime — even after setup:\n\n```bash\nclaude-backup backend set github   # switch to GitHub\nclaude-backup backend set local    # switch to local-only\nclaude-backup backend set git --remote <url>  # custom remote\n```\n\nBackups go to `~/.claude-backup/` as a local git repo. Everything works the same — sync, restore, peek, export/import.\n\n---\n\n## Backup Schedule\n\nControl how often backups run:\n\n```bash\nclaude-backup schedule daily    # Every day at 3:00 AM (default)\nclaude-backup schedule 6h       # Every 6 hours\nclaude-backup schedule hourly   # Every hour\nclaude-backup schedule off      # Disable automatic backups\n```\n\n---\n\n## Restore Everything\n\nRestore all sessions at once — useful for a fresh machine or disaster recovery:\n\n```bash\nclaude-backup restore --all             # restore every session\nclaude-backup restore --all --force     # overwrite existing sessions\n```\n\n---\n\n## Claude Code Plugin\n\nFor the maintained agent skill shared with Codex, install it from Tomstack:\n\n```bash\nnpx skills@latest add tombelieber/tomstack --skill=backup\n```\n\nOr install the whole managed Claude skill bundle:\n\n```bash\nclaude plugin marketplace add tombelieber/tomstack\nclaude plugin install tomstack-skills@tomstack\n```\n\nUse this standalone product plugin when you specifically want its bundled CLI\nwith no `npm install`:\n\n```bash\n/plugin marketplace add tombelieber/claude-backup\n/plugin install claude-backup@claude-backup\n```\n\nThat's it. The plugin bundles the CLI — the agent runs it directly from the plugin cache. No global install, no npx, no PATH setup.\n\n---\n\n<details>\n<summary><strong>All Commands</strong></summary>\n<br>\n\n| Command | Description |\n| --- | --- |\n| `claude-backup` | Interactive first-time setup |\n| `claude-backup sync` | Backup config + sessions |\n| `claude-backup sync --config-only` | Backup config only (fast, < 1 sec) |\n| `claude-backup sync --sessions-only` | Backup sessions only |\n| `claude-backup status` | Show backup status |\n| `claude-backup export-config` | Export config as portable tarball |\n| `claude-backup import-config <file>` | Import config from tarball |\n| `claude-backup import-config <file> --force` | Import config, overwriting existing files |\n| `claude-backup peek <uuid>` | Preview a session's contents |\n| `claude-backup restore --list` | List all backed-up sessions |\n| `claude-backup restore --last N` | List last N sessions |\n| `claude-backup restore --date YYYY-MM-DD` | Filter by UTC date |\n| `claude-backup restore --project NAME` | Filter by project name |\n| `claude-backup restore <uuid>` | Restore a specific session |\n| `claude-backup restore <uuid> --force` | Overwrite existing session |\n| `claude-backup restore --all` | Restore all sessions at once |\n| `claude-backup restore --all --force` | Restore all, overwrite existing |\n| `claude-backup backend set <mode>` | Switch backend (github, git, local) |\n| `claude-backup schedule <freq>` | Set frequency (off, daily, 6h, hourly) |\n| `claude-backup uninstall` | Remove scheduler and optionally delete data |\n| `claude-backup <any> --json` | Structured JSON output (for scripts/agents) |\n| `claude-backup init --local` | Force local-only mode (no GitHub) |\n| `claude-backup init --backend <mode>` | Set backend during init |\n\n</details>\n\n<details>\n<summary><strong>Security</strong></summary>\n<br>\n\n- **Credentials are never backed up.** `.credentials.json` and `.encryption_key` are hardcoded exclusions.\n- **GitHub repo is private** by default.\n- **`export-config` warns** if any file appears to contain sensitive content (tokens, secrets, passwords).\n- **`import-config` does not overwrite** existing credentials.\n\n</details>\n\n<details>\n<summary><strong>What's Excluded</strong></summary>\n<br>\n\n| Item | Why |\n| --- | --- |\n| `.credentials.json` | Auth tokens — security risk |\n| `.encryption_key` | Encryption key — security risk |\n| `plugins/` | Re-downloadable from registry |\n| `debug/`, `file-history/` | Transient logs and edit history |\n| `cache/`, `.search_cache/`, `.tmp/`, `paste-cache/` | Caches, rebuilt automatically |\n| `session-env/`, `shell-snapshots/` | Runtime state |\n| `statsig/`, `telemetry/`, `usage-data/` | Analytics, not user data |\n| `todos/`, `teams/`, `plans/`, `ide/` | Ephemeral per-session data |\n\n</details>\n\n<details>\n<summary><strong>Storage Layout</strong></summary>\n<br>\n\n```text\n~/.claude-backup/                         # Git repo -> private GitHub repo\n├── manifest.json                         # Root manifest (aggregates all machines)\n├── machines/\n│   └── <machine-slug>/                   # Per-machine namespace\n│       ├── manifest.json                 # Machine-specific metadata\n│       ├── config/                       # Config profile\n│       │   ├── settings.json\n│       │   ├── settings.local.json\n│       │   ├── CLAUDE.md\n│       │   ├── agents/\n│       │   ├── hooks/\n│       │   ├── skills/\n│       │   └── rules/\n│       ├── session-index.json            # Auto-generated, gitignored\n│       ├── projects/                     # Sessions (gzipped)\n│       │   ├── -Users-foo-myproject/\n│       │   │   ├── session-abc.jsonl.gz\n│       │   │   └── sessions-index.json\n│       │   └── ...\n│       └── history.jsonl.gz             # Command history (gzipped)\n└── ...                                   # Other machines\n```\n\nSessions are namespaced by machine — backups from multiple devices stay organized and searchable. Existing v3.1 backups are auto-migrated on first sync.\n\n| Location | Contents |\n| --- | --- |\n| `~/.claude-backup/` | Local compressed backups + git repo |\n| `github.com/<you>/claude-backup-data` | Remote private repo |\n| `~/Library/LaunchAgents/com.claude-backup.plist` | macOS scheduler |\n\n</details>\n\n<details>\n<summary><strong>Requirements</strong></summary>\n<br>\n\n- **macOS** (Linux coming soon)\n- **git**\n- **gzip** (built-in on macOS)\n- **python3** (built-in on macOS since Catalina)\n- **gh** ([GitHub CLI](https://cli.github.com)) — *optional*. Enables remote backup. Without it, backups are local-only.\n\n</details>\n\n<details>\n<summary><strong>Uninstall</strong></summary>\n<br>\n\n```bash\nclaude-backup uninstall\n```\n\nRemoves the daily scheduler and optionally deletes local backup data. Delete the GitHub repo separately:\n\n```bash\ngh repo delete claude-backup-data\n```\n\n</details>\n\n---\n\n## Related\n\n- **[claude-view](https://github.com/tombelieber/claude-view)** — 10 Claude sessions running. What are they doing? `npx claude-view`\n\n---\n\n<div align=\"center\">\n\nIf **claude-backup** saves your sessions, consider giving it a star. It helps others discover this tool.\n\n<a href=\"https://github.com/tombelieber/claude-backup/stargazers\">\n  <img src=\"https://img.shields.io/github/stars/tombelieber/claude-backup?style=for-the-badge&logo=github\" alt=\"Star on GitHub\">\n</a>\n\n<br><br>\n\n[MIT](LICENSE)\n\n</div>\n",
  "bytes": 11476,
  "sha": "bf73e72e4e370d674116a124e0f89c89f2fe7c578d78930ba1f47f7be583e93b",
  "repo_slug": "tombelieber/claude-backup",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tombelieber_claude_backup_claude_backup_04cd9e42/readme"
}