Skip to content

README.md

Latest commit

 

History

History
477 lines (360 loc) · 13.2 KB

README.md

File metadata and controls

477 lines (360 loc) · 13.2 KB

Claude Code Conversation Sync

Synchronize your Claude Code conversations across multiple computers using git, with optional encryption.

Why?

Claude Code stores conversations locally in ~/.claude/, which means:

  • ❌ Conversations are machine-locked
  • ❌ No sync between computers
  • ❌ Risk of losing conversations if machine fails
  • ❌ Can't easily share with team members

This tool fixes that:

  • ✅ Sync conversations across all your machines
  • ✅ Git-based version control
  • ✅ Optional transparent encryption (git-crypt)
  • ✅ Local backups with auto-cleanup
  • ✅ Works with any git provider (GitHub, Bitbucket, GitLab, etc.)

Quick Start

Installation

git clone https://github.com/porkchop/claude-code-sync.git
cd claude-code-sync
chmod +x claude-*

Add to your PATH (add this to ~/.bashrc or ~/.zshrc):

export PATH="$HOME/claude-code-sync:$PATH"

Initial Setup (First Machine)

  1. Create a private git repository for your conversations:

    GitHub:

    • Go to https://github.com/new
    • Name it something like claude-conversations
    • Select Private
    • Leave "Initialize with README" unchecked (empty repo)
    • Click "Create repository"
    • Copy the SSH URL: git@github.com:username/claude-conversations.git

    Bitbucket:

    • Go to https://bitbucket.org/repo/create
    • Name it something like claude-conversations
    • Set Access level to Private
    • Click "Create repository"
    • Copy the SSH URL: git@bitbucket.org:username/claude-conversations.git

    GitLab:

    • Go to https://gitlab.com/projects/new
    • Name it something like claude-conversations
    • Set Visibility to Private
    • Uncheck "Initialize repository with a README"
    • Click "Create project"
    • Copy the SSH URL: git@gitlab.com:username/claude-conversations.git

    Note: Make sure you have SSH keys set up for your git provider. If git clone git@github.com:... works for your other repos, you're all set. Otherwise, see your provider's SSH key documentation.

  2. Configure sync settings:

    claude-config

  3. Create your first backup (safety first!):

    claude-backup

  4. Initialize the repository:

    claude-sync-init

  5. (Optional) Enable encryption:

    claude-enable-encryption

    Save the encryption key to your password manager (KeePass, 1Password, etc.)

  6. Exit Claude Code, then push your conversations:

    claude-sync-push

    ⚠️ Important: Claude Code only writes conversations to disk when you exit. Always exit Claude Code before running claude-sync-push to ensure you're syncing the latest state.

Setup on Additional Machines

  1. Clone this tool:

    git clone https://github.com/porkchop/claude-code-sync.git
cd claude-code-sync
chmod +x claude-*

  2. Add to PATH (same as above)

  3. Configure with same remote URL:

    claude-config

  4. Create a backup of this machine's existing conversations:

    claude-backup

  5. Initialize and clone the repository:

    claude-sync-init

  6. If the repository is encrypted, restore your key and unlock:

    claude-restore-encryption-key

    This will restore your key from your password manager and unlock the repository.

  7. Sync conversations to your local Claude:

    claude-sync-pull

  8. Exit Claude Code (if running), then add this machine's conversations:

    claude-sync-push

    ⚠️ Important: Always exit Claude Code before claude-sync-push to capture the latest conversation state.

  9. Restart Claude Code to see all synced conversations

Daily Usage

Before Starting Work

claude-sync-pull
# Then start Claude Code

After Working / Before Switching Machines

# Exit Claude Code first (important!)
claude-sync-push

⚠️ Critical: Claude Code only writes conversations to disk when you exit. Always:

  1. Exit Claude Code completely
  2. Run claude-sync-push
  3. Then switch machines or close your terminal

If you run claude-sync-push while Claude Code is still running, you won't sync your latest work!

Check Status

claude-sync-status  # Shows config, sync state, conversation counts

Manage Configuration

claude-config  # Edit settings interactively

Features

🔄 Multi-Machine Sync

Conversations accumulate across all machines:

  • Machine A has conversations 1, 2, 3
  • Machine B has conversations 3, 4, 5 (conversation 3 updated more recently)
  • After syncing: Both machines have 1, 2, 3 (B's version), 4, 5

⚠️ Important: Claude Code stores conversations by project path. For sync to work correctly, your projects must be at the same absolute paths on all machines. For example, if you work in /home/alice/projects/myapp on one machine, use the same path on others.

If you need to move a project, use claude-migrate-project to update the conversation paths (see Utilities below).

🔐 Optional Encryption

Enable transparent encryption with git-crypt. See Requirements section for installation on your platform.

First machine (enable encryption):

claude-sync-init             # Initialize repo first
claude-enable-encryption     # Set up encryption, generates key
claude-sync-push             # Push encrypted conversations

The script will generate an encryption key and display it in base64 format. Save this key to your password manager immediately!

On other machines:

claude-restore-encryption-key  # Restore key from password manager
claude-sync-init               # Clone and unlock repository
claude-sync-pull               # Sync conversations

💾 Backup & Restore

Create backups:

claude-backup  # Creates timestamped backup

List backups:

claude-backup-list

Restore from backup:

claude-restore <backup-name>

Backups are:

  • Compressed (tar.gz)
  • Timestamped with machine name
  • Stored locally (not synced)
  • Auto-cleaned based on retention policy (default: 30 days)

Configuration

Configuration uses three layers (priority: highest to lowest):

  1. Environment variables - CLAUDE_SYNC_*
  2. Local config - .claude-sync-config.local (machine-specific, gitignored)
  3. Shared config - .claude-sync-config (defaults, version controlled)

Available Settings

  • CLAUDE_SYNC_REMOTE - Git remote URL (required)
  • CLAUDE_SYNC_BRANCH - Git branch (default: main)
  • CLAUDE_SYNC_ENCRYPTION - Enable encryption (default: false)
  • CLAUDE_BACKUP_RETENTION_DAYS - Backup retention (default: 30)
  • CLAUDE_DATA_DIR - Claude data directory (default: ~/.claude)
  • CLAUDE_SYNC_VERBOSE - Verbose output (default: false)

See CONFIGURATION.md for detailed configuration guide.

How It Works

Sync Strategy

Init (claude-sync-init):

  1. Clones conversations repository from remote (or initializes fresh if empty)
  2. Detects encryption and prompts for unlock if needed
  3. Prepares repository for push/pull operations

Push (claude-sync-push):

  1. Pulls latest from remote (avoid conflicts)
  2. Merges local conversations using rsync --update
  3. Commits and pushes to remote

Pull (claude-sync-pull):

  1. Pulls from remote
  2. Merges into ~/.claude/ (preserves newer files)

Conflict Resolution:

  • Same conversation UUID: Newer file wins (based on modification time)
  • Different UUIDs: All conversations kept (merged)
  • History: Deduplicated and merged

What Gets Synced

~/.claude/
├── projects/        → Conversation files (.jsonl)
├── file-history/    → File edit history
├── todos/           → Todo lists
└── history.jsonl    → Command history

What's Excluded

  • .credentials.json (never synced)
  • Debug files
  • Local backups

Security & Privacy

⚠️ Important: Conversations contain:

  • Full text of all messages
  • All code discussed or generated
  • File paths and project structure
  • System information

Recommendations:

  • ✅ Use private git repository
  • ✅ Enable encryption for sensitive work
  • ✅ Store encryption key in password manager (KeePass, 1Password, etc.)
  • ✅ Never commit real API keys or secrets in conversations

See SECURITY.md for full security analysis and encryption guide.

Commands Reference

All commands support --version or -v to display version information.

Setup Commands

  • claude-config - Interactive configuration wizard
  • claude-sync-init - Initialize/clone the conversations repository

Sync Commands

  • claude-sync-push - Sync local → remote (pull, merge, push)
  • claude-sync-pull - Sync remote → local
  • claude-sync-status - Show status and configuration

Backup Commands

  • claude-backup - Create timestamped backup
  • claude-backup-list - List available backups
  • claude-restore <name> - Restore from backup

Encryption Commands

  • claude-enable-encryption - Enable git-crypt encryption
  • claude-restore-encryption-key - Restore encryption key from password manager

Utility Commands

  • claude-migrate-project <old-path> <new-path> - Migrate conversations when renaming/moving a project

Example: If you move a project from /home/user/old-name to /home/user/new-name:

claude-migrate-project /home/user/old-name /home/user/new-name
mv /home/user/old-name /home/user/new-name

Troubleshooting

Latest changes not syncing

Problem: You ran claude-sync-push but your latest conversation changes aren't showing up on other machines.

Solution: Claude Code only writes conversations to disk when you exit. Always:

  1. Type /exit in Claude Code
  2. Wait for it to fully close
  3. Then run claude-sync-push

"Repository not initialized" error

  • Run claude-sync-init before using claude-sync-push or claude-sync-pull

"Repository is encrypted but locked" error

  • Restore your encryption key: claude-restore-encryption-key
  • Then re-run claude-sync-init to unlock

Conversations not appearing after sync

  • Restart Claude Code after claude-sync-pull
  • Check permissions: ls -la ~/.claude/projects

Git push fails

  • Verify remote configured: git remote -v
  • Check git credentials
  • Ensure you have write access to repository

Encryption key mismatch

  • Ensure you're using the correct key from your password manager
  • If key was lost, you'll need to start fresh with a new encrypted repo

Configuration errors

  • Run claude-sync-status to see current config
  • Run claude-config to reconfigure
  • Check .claude-sync-config.local exists

Requirements

Core Dependencies

  • Bash 4.0+
  • Git
  • rsync
  • tar, gzip
  • git-crypt (optional, for encryption)

Platform Support

✅ Linux (Tested & Recommended)

  • Ubuntu/Debian - Fully tested and working
  • Fedora/RHEL/CentOS - Should work (standard bash/git/rsync)
  • Arch Linux - Should work
  • Pop!_OS - Should work (Ubuntu-based)

All standard Linux distributions with bash 4.0+ should work out of the box.

✅ macOS (Should Work)

  • macOS 10.14+ - Should work
  • Comes with bash, git, rsync by default
  • May need to install git-crypt via Homebrew
  • Note: Default shell is zsh, but bash scripts run fine

✅ Windows WSL (Should Work)

  • WSL 1 or WSL 2 with Ubuntu/Debian - Should work
  • Treats WSL as a Linux environment
  • All Linux instructions apply

❌ Windows Native (Not Supported)

  • Git Bash - Limited support, not recommended
  • PowerShell - Not compatible (bash scripts only)
  • Native Windows - Not supported

Installing git-crypt (for encryption)

Ubuntu/Debian/Pop!_OS:

sudo apt update
sudo apt install git-crypt

Fedora/RHEL/CentOS:

sudo dnf install git-crypt     # Fedora/RHEL 8+
# OR
sudo yum install git-crypt     # CentOS/RHEL 7

Arch Linux:

sudo pacman -S git-crypt

macOS:

brew install git-crypt

Windows WSL: Use the Linux distribution's package manager (usually apt for Ubuntu):

sudo apt update
sudo apt install git-crypt

Versioning

This project uses Semantic Versioning. Check the version of any command:

claude-sync-push --version
claude-backup --version
# etc.

See CHANGELOG.md for release history.

Contributing

Contributions welcome! See CONTRIBUTING.md for detailed guidelines.

Quick summary:

  • Follow existing code style
  • Add --version support to new commands
  • Update documentation
  • Test on fresh install
  • Ensure scripts return to original directory

For Maintainers

Release process:

./claude-release patch  # or minor, major
# Edit CHANGELOG.md with release notes
# Push: git push origin master --tags

See CONTRIBUTING.md for full release documentation.

License

MIT License - see LICENSE file

Support

Acknowledgments

Built for the Claude Code community. Inspired by the need to work seamlessly across multiple development machines.