<div align="center">

# Claude Code History Sync

**Sync your Claude Code conversations across all your machines**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)](https://github.com/bokiko/claude-history-sync-guide)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/bokiko/claude-history-sync-guide/pulls)

---

*Never lose your Claude Code conversation history again.*

*Switch between your laptop, desktop, and work computer seamlessly.*

---

[Why Use This?](#-why-use-this) |
[Quick Start](#-quick-start-5-minutes) |
[Daily Use](#-daily-workflow) |
[Troubleshooting](#-troubleshooting)

</div>

---

## What is This?

When you use **Claude Code** (the CLI tool from Anthropic), all your conversations are saved locally on your computer in a hidden folder called `~/.claude/projects/`.

**The Problem:** If you switch to a different computer, all those conversations are gone. You can't continue where you left off.

**The Solution:** This guide shows you how to sync your Claude Code history to GitHub (or your own server) so you can access it from any machine.

---

## Why Use This?

| Benefit | Description |
|---------|-------------|
| **Continue Anywhere** | Start a conversation on your laptop, continue on your desktop |
| **Automatic Backup** | Never lose your valuable AI coding sessions |
| **Version History** | Git tracks every change, so you can go back in time |
| **Your Data, Your Control** | Uses your private GitHub repo - nobody else can see it |
| **Simple Commands** | Just two commands: `pull` and `push` |

---

## How It Works (Simple Explanation)

```
Your Computer                         GitHub (Private Repo)
     |                                        |
     |   ~/claude-sync.sh push   -------->    |
     |                                        |
     |   <--------   ~/claude-sync.sh pull    |
     |                                        |
```

1. **Push** = Upload your conversations to GitHub
2. **Pull** = Download conversations from GitHub

That's it! Two commands to stay in sync.

---

## Before You Start

You need these things set up first:

| Requirement | How to Check | What It Is |
|-------------|--------------|------------|
| **Git** | Type `git --version` | A tool for tracking file changes |
| **SSH Key** | Type `ls ~/.ssh/id_ed25519.pub` | A secure way to connect to GitHub |
| **GitHub Account** | Go to github.com | Where your history will be stored |

**Don't have these?** No problem! Follow the setup guide below for your operating system.

---

## Quick Start (5 Minutes)

### Step 1: Set Up Git and SSH (Skip if Already Done)

<details>
<summary><strong>Click here if you're on macOS</strong></summary>

Open **Terminal** (press `Cmd + Space`, type "Terminal", press Enter).

**Install Git:**
```bash
# Check if you have Git
git --version

# If you see "command not found", install it:
xcode-select --install
```

**Create SSH Key:**
```bash
# Check if you already have an SSH key
ls ~/.ssh/id_ed25519.pub

# If you see "No such file", create one:
ssh-keygen -t ed25519 -C "[email protected]"
# Press Enter 3 times to accept defaults (no passphrase is fine)

# Copy your SSH key to clipboard
pbcopy < ~/.ssh/id_ed25519.pub
```

**Add SSH Key to GitHub:**
1. Go to https://github.com/settings/keys
2. Click "New SSH key"
3. Title: "My Mac"
4. Key: Press `Cmd + V` to paste
5. Click "Add SSH key"

**Test it works:**
```bash
ssh -T [email protected]
# You should see: "Hi username! You've successfully authenticated"
```

</details>

<details>
<summary><strong>Click here if you're on Ubuntu/Linux</strong></summary>

Open **Terminal** (press `Ctrl + Alt + T`).

**Install Git:**
```bash
# Check if you have Git
git --version

# If you see "command not found", install it:
sudo apt update
sudo apt install git -y
```

**Create SSH Key:**
```bash
# Check if you already have an SSH key
ls ~/.ssh/id_ed25519.pub

# If you see "No such file", create one:
ssh-keygen -t ed25519 -C "[email protected]"
# Press Enter 3 times to accept defaults (no passphrase is fine)

# View your SSH key (you'll need to copy this)
cat ~/.ssh/id_ed25519.pub
```

**Add SSH Key to GitHub:**
1. Copy the output from the `cat` command above
2. Go to https://github.com/settings/keys
3. Click "New SSH key"
4. Title: "My Linux Machine"
5. Key: Paste the key
6. Click "Add SSH key"

**Test it works:**
```bash
ssh -T [email protected]
# You should see: "Hi username! You've successfully authenticated"
```

</details>

<details>
<summary><strong>Click here if you're on Windows</strong></summary>

**Install Git for Windows:**
1. Download from https://git-scm.com/download/win
2. Run the installer (use all default options)
3. Open **Git Bash** (search for it in Start menu)

**Create SSH Key:**
```bash
# Check if you already have an SSH key
ls ~/.ssh/id_ed25519.pub

# If you see "No such file", create one:
ssh-keygen -t ed25519 -C "[email protected]"
# Press Enter 3 times to accept defaults (no passphrase is fine)

# Copy your SSH key to clipboard
clip < ~/.ssh/id_ed25519.pub
```

**Add SSH Key to GitHub:**
1. Go to https://github.com/settings/keys
2. Click "New SSH key"
3. Title: "My Windows PC"
4. Key: Press `Ctrl + V` to paste
5. Click "Add SSH key"

**Test it works:**
```bash
ssh -T [email protected]
# You should see: "Hi username! You've successfully authenticated"
```

</details>

---

### Step 2: Create Your Private Repository

You need a private place on GitHub to store your history. Here's how:

1. **Go to this link:** https://github.com/new

2. **Fill in the form:**
   - Repository name: `claude-history`
   - Description: `My Claude Code conversation history`
   - **IMPORTANT:** Select **Private** (not Public!)
   - Leave everything else as default

3. **Click "Create repository"**

4. **Copy the SSH URL** (looks like: `[email protected]:YOUR_USERNAME/claude-history.git`)

---

### Step 3: Download and Set Up the Sync Script

**Open Terminal** (or Git Bash on Windows) and run these commands one at a time:

```bash
# Go to your home folder
cd ~

# Download the sync script
curl -O https://raw.githubusercontent.com/bokiko/claude-history-sync-guide/main/claude-sync.sh

# Make it executable
chmod +x ~/claude-sync.sh
```

---

### Step 4: Configure the Script

Open the script in a text editor:

**On macOS:**
```bash
nano ~/claude-sync.sh
```

**On Linux:**
```bash
nano ~/claude-sync.sh
```

**On Windows (Git Bash):**
```bash
notepad ~/claude-sync.sh
```

**Find these two lines near the top (around line 20):**

```bash
REPO_URL="[email protected]:YOUR_USERNAME/claude-history.git"
MACHINE="my-machine"
```

**Change them to:**

```bash
REPO_URL="[email protected]:YOUR_ACTUAL_USERNAME/claude-history.git"
MACHINE="my-laptop"    # Or whatever name you want for this computer
```

**Save and exit:**
- If using `nano`: Press `Ctrl + X`, then `Y`, then `Enter`
- If using `notepad`: Click File > Save, then close

---

### Step 5: Test It!

**First, pull (download) any existing history:**
```bash
~/claude-sync.sh pull
```

You should see:
```
Cloning repository...
Pulling latest history...
Done! Available machines:
```

**If you've used Claude Code, push (upload) your history:**
```bash
~/claude-sync.sh push
```

You should see:
```
Syncing Claude history from my-laptop...
Successfully pushed from my-laptop!
```

**Congratulations! You're all set up!**

---

## Daily Workflow

Using this is simple. Just remember two commands:

### When You Start Working

```bash
~/claude-sync.sh pull
```

This downloads the latest history from all your machines.

### When You're Done Working

```bash
~/claude-sync.sh push
```

This uploads your new conversations to GitHub.

---

## Adding More Machines

Want to sync another computer? Follow these steps:

### On the New Machine:

1. **Complete Step 1** (Git and SSH setup) if not already done

2. **Download the sync script:**
   ```bash
   cd ~
   curl -O https://raw.githubusercontent.com/bokiko/claude-history-sync-guide/main/claude-sync.sh
   chmod +x ~/claude-sync.sh
   ```

3. **Edit the script** (same as Step 4), but use a **different machine name:**
   ```bash
   REPO_URL="[email protected]:YOUR_USERNAME/claude-history.git"  # Same URL
   MACHINE="my-desktop"  # DIFFERENT name for this machine!
   ```

4. **Pull existing history:**
   ```bash
   ~/claude-sync.sh pull
   ```

Now both machines are syncing to the same repo!

---

## What Gets Synced

Your GitHub repo will look like this:

```
claude-history/
├── my-laptop/
│   ├── project-website/
│   │   └── conversations.jsonl
│   └── project-api/
│       └── conversations.jsonl
├── my-desktop/
│   └── project-website/
│       └── conversations.jsonl
└── README.md
```

Each machine gets its own folder, so there are no conflicts.

---

## Command Reference

| Command | What It Does |
|---------|--------------|
| `~/claude-sync.sh pull` | Download history from GitHub |
| `~/claude-sync.sh push` | Upload your history to GitHub |
| `~/claude-sync.sh status` | Show sync info and machine list |

---

## Automation (Optional)

### Auto-Pull When You Open Terminal

Add this to your shell config so it automatically pulls when you open a new terminal:

**macOS (zsh):**
```bash
echo 'if [ -f ~/claude-sync.sh ]; then ~/claude-sync.sh pull 2>/dev/null; fi' >> ~/.zshrc
```

**Linux (bash):**
```bash
echo 'if [ -f ~/claude-sync.sh ]; then ~/claude-sync.sh pull 2>/dev/null; fi' >> ~/.bashrc
```

**Windows (Git Bash):**
```bash
echo 'if [ -f ~/claude-sync.sh ]; then ~/claude-sync.sh pull 2>/dev/null; fi' >> ~/.bashrc
```

### Auto-Push Every Hour

**macOS/Linux (using cron):**
```bash
# Open cron editor
crontab -e

# Add this line at the bottom
0 * * * * ~/claude-sync.sh push 2>/dev/null
```

---

## Troubleshooting

### "Permission denied" Error

**Problem:** Git can't connect to GitHub.

**Solution:**
```bash
# Start the SSH agent
eval "$(ssh-agent -s)"

# Add your key
ssh-add ~/.ssh/id_ed25519

# Test the connection
ssh -T [email protected]
```

If it still doesn't work, make sure your SSH key is added to GitHub (see Step 1).

---

### "Nothing to commit" Message

**This is normal!** It means there are no new conversations to sync.

---

### "Claude projects directory not found" Error

**Problem:** You haven't used Claude Code yet, so there's nothing to sync.

**Solution:** Use Claude Code at least once, then try again.

---

### Merge Conflicts

**Problem:** You edited the same file on two machines.

**Solution:**
```bash
cd ~/claude-history-sync
git stash
git pull
git stash pop
```

If that doesn't work:
```bash
cd ~/claude-history-sync
git reset --hard origin/main
```

This will lose local changes, so push from your other machine first.

---

### "Repository not found" Error

**Problem:** The repo URL is wrong or doesn't exist.

**Solution:**
1. Check the URL in `~/claude-sync.sh` is correct
2. Make sure the repo exists on GitHub
3. Make sure it's spelled exactly right (case-sensitive)

---

## Self-Hosted Options

Don't want to use GitHub? You can use your own server instead.

<details>
<summary><strong>Option 1: Your Own Git Server (Gitea, GitLab)</strong></summary>

If you have a self-hosted Git server:

1. Create a repo called `claude-history` on your server
2. Edit `~/claude-sync.sh` and change `REPO_URL`:
   ```bash
   REPO_URL="[email protected]:username/claude-history.git"
   ```
3. Everything else works the same!

</details>

<details>
<summary><strong>Option 2: NAS (Synology, QNAP)</strong></summary>

Most NAS systems support Git:

1. Install Git Server from your NAS app store
2. Create a bare repo
3. Use the SSH URL: `ssh://user@nas-ip/volume1/git/claude-history.git`

</details>

<details>
<summary><strong>Option 3: Any Server with SSH</strong></summary>

Use rsync for simple file sync:

```bash
# Push to server
rsync -avz ~/.claude/projects/ user@server:/backup/claude-history/

# Pull from server
rsync -avz user@server:/backup/claude-history/ ~/claude-backup/
```

</details>

---

## Privacy & Security

**Important things to know:**

- **Always use a PRIVATE repository** - your conversations may contain sensitive code
- The `.gitignore` file excludes common sensitive files (`.env`, `.pem`, etc.)
- Review your history before pushing if you're worried about sensitive content
- GitHub is owned by Microsoft - if that concerns you, use a self-hosted option

---

## FAQ

<details>
<summary><strong>Will this slow down Claude Code?</strong></summary>

No. The sync script only runs when you manually run it. It doesn't affect Claude Code's performance at all.

</details>

<details>
<summary><strong>Can I sync specific projects only?</strong></summary>

Not with this script. It syncs everything in `~/.claude/projects/`. If you need selective sync, you'd need to modify the script.

</details>

<details>
<summary><strong>What if I delete a conversation locally?</strong></summary>

The deleted conversation will still exist in your Git history. If you push after deleting, the file will be removed from the latest version but can still be recovered from Git history.

</details>

<details>
<summary><strong>Is this officially supported by Anthropic?</strong></summary>

No. This is a community solution. Claude Code may change how it stores data in the future, which could break this script.

</details>

---

## Contributing

Found a bug? Have an idea for improvement?

1. Open an issue: https://github.com/bokiko/claude-history-sync-guide/issues
2. Or submit a pull request!

All contributions are welcome.

---

## License

MIT License - Use however you like. See [LICENSE](LICENSE) for details.

---

<div align="center">

**Made for the Claude Code community**

*Star this repo if you found it useful!*

</div>