Introduction
# Clawdbot Sync 🔄
Synchronize memory, preferences, and skills between multiple Clawdbot instances over Tailscale/SSH.
## Features
- **Bi-directional sync** between Clawdbot instances - **Smart conflict resolution** (newest wins, or merge for logs) - **Selective sync** — choose what to sync - **Peer discovery** via Tailscale - **Dry-run mode** for preview
## Commands
| Command | Action | |---------|--------| | `/sync` | Show status and configured peers | | `/sync status` | Check connection to all peers | | `/sync now [peer]` | Sync with peer (or all) | | `/sync push [peer]` | Push local changes to peer | | `/sync pull [peer]` | Pull changes from peer | | `/sync add <name> <host> [user] [path]` | Add a peer | | `/sync remove <name>` | Remove a peer | | `/sync diff [peer]` | Show what would change | | `/sync history` | Show sync history |
## Setup
### 1. Configure Peers
```bash handler.sh add mac-mini 100.95.193.55 clawdbot /Users/clawdbot/clawd $WORKSPACE handler.sh add server 100.89.48.26 clawdbot /home/clawdbot/clawd $WORKSPACE ```
### 2. Ensure SSH Access
Both machines need SSH key auth: ```bash ssh-copy-id [email protected] ```
### 3. Test Connection
```bash handler.sh status $WORKSPACE ```
## What Gets Synced
| Item | Default | Notes | |------|---------|-------| | `memory/` | ✅ Yes | All memory files and skill data | | `MEMORY.md` | ✅ Yes | Main memory file | | `USER.md` | ✅ Yes | User profile | | `IDENTITY.md` | ❌ No | Each instance has its own identity | | `skills/` | ⚙️ Optional | Installed skills | | `config/` | ❌ No | Instance-specific config |
## Handler Commands
```bash handler.sh status $WORKSPACE # Check peers and connection handler.sh sync <peer> $WORKSPACE # Bi-directional sync handler.sh push <peer> $WORKSPACE # Push to peer handler.sh pull <peer> $WORKSPACE # Pull from peer handler.sh diff <peer> $WORKSPACE # Show differences handler.sh add <name> <host> <user> <path> $WS # Add peer handler.sh remove <name> $WORKSPACE # Remove peer handler.sh history $WORKSPACE # Sync history handler.sh auto <on|off> $WORKSPACE # Auto-sync on heartbeat ```
## Conflict Resolution
1. **Timestamp-based**: Newer file wins 2. **Merge for logs**: Append-only files are merged 3. **Skip conflicts**: Option to skip conflicting files 4. **Manual resolution**: Flag for review
## Data Files
Stored in `$WORKSPACE/memory/clawdbot-sync/`:
| File | Purpose | |------|---------| | `peers.json` | Configured peers | | `history.json` | Sync history log | | `config.json` | Sync preferences | | `conflicts/` | Conflicting files for review |
## Example Session
``` User: /sync now mac-mini Bot: 🔄 Syncing with mac-mini (100.95.193.55)...
📤 Pushing: 3 files changed • memory/streaming-buddy/preferences.json • memory/2026-01-26.md • MEMORY.md 📥 Pulling: 1 file changed • memory/2026-01-25.md ✅ Sync complete! 4 files synchronized. ```
## Requirements
- `rsync` (for efficient file sync) - `ssh` (for secure transport) - Tailscale or direct network access between peers - SSH key authentication configured
## Security
- Uses SSH for all transfers (encrypted) - No passwords stored (key-based auth only) - Sync paths are restricted to workspace - No system files are ever synced