Workspace Sync

SKILL.md

---
name: workspace-sync
description: Sync agent workspaces (skills, memory, config) across machines using Git or rsync. Use when you need to synchronize agent workspaces between Ada, Spock, and Scotty across local machines, Pi, and Mac environments. Zero-token bash scripts for selective sync with secrets exclusion.
---

# Workspace Sync

Synchronize agent workspaces across multiple machines using zero-token bash scripts. Supports Git-based and rsync-based workflows with selective file exclusion.

## Architecture

**Agents:**
- **Ada** - Primary agent (ada-gateway)
- **Spock** - Research agent (spock workspace)
- **Scotty** - Operations agent (scotty workspace)

**Sync Targets:**
- Local machines (ada-gateway, spock, scotty)
- Pi (Raspberry Pi)
- Mac (macOS machine)

**Shared Repository:** `henrino3/clawd` (Git-based sync backbone)

## What Gets Synced

- `skills/` - Custom skills and scripts
- `memory/` - Daily memory files
- `memory.md` - Long-term memory
- `AGENTS.md`, `SOUL.md`, `IDENTITY.md` - Agent configuration
- `TOOLS.md` - Tool notes

## What Gets Excluded

See `config/sync-exclude.txt` for the full list:
- Secrets and credentials (`.env`, `*.key`, `*.pem`)
- Large files (`*.mp4`, `*.zip`, `*.tar.gz`)
- System files (`.DS_Store`, `node_modules/`)
- Local runtime files (`logs/`, `*.pid`)

## Usage

### Sync to Pi

Push current workspace to Pi:

```bash
./scripts/sync-to-pi.sh
```

Options:
- `-n, --dry-run` - Preview changes without applying
- `-h, --host HOSTNAME` - Override Pi hostname (default: pi@raspberrypi.local)

### Sync from Pi

Pull workspace from Pi to local:

```bash
./scripts/sync-from-pi.sh
```

Options:
- `-n, --dry-run` - Preview changes without applying
- `-h, --host HOSTNAME` - Override Pi hostname

### Sync All

Synchronize across all configured machines:

```bash
./scripts/sync-all.sh
```

This script:
1. Commits local changes to Git
2. Pushes to henrino3/clawd
3. Syncs to Pi via rsync
4. Optionally syncs to Mac (if configured)

## Git Workflow

The shared repository provides version control and conflict resolution:

```bash
# On any machine:
cd ~/clawd
git pull                    # Get latest changes
# Make modifications
git add .
git commit -m "Update"
git push                    # Share with other machines
```

## Rsync vs Git

**Use Git for:**
- Tracked changes with history
- Conflict resolution
- Collaboration across multiple agents

**Use rsync for:**
- Fast one-way sync to Pi
- Selective sync with exclusions
- Backup without version control

## Conflict Resolution

When conflicts occur:

1. **Git conflicts** - Resolve manually in affected files, commit
2. **Rsync conflicts** - Newer files overwrite older (use `--dry-run` first)

## Setup Requirements

### Pi SSH Access

Ensure SSH key authentication is configured:

```bash
ssh-copy-id pi@raspberrypi.local
```

### Git Configuration

Clone the shared repository on each machine:

```bash
git clone https://github.com/henrino3/clawd.git ~/clawd
cd ~/clawd
git config user.name "Your Name"
git config user.email "your@email.com"
```

### Environment Variables

Optional overrides in `~/.bashrc` or `~/.zshrc`:

```bash
export CLAWD_PI_HOST="pi@192.168.1.100"  # Override Pi hostname
export CLAWD_MAC_HOST="mac@macmini.local"  # Mac sync target
```

## Automation

### Cron Jobs

Sync automatically every hour:

```bash
0 * * * * cd ~/clawd/skills/workspace-sync && ./scripts/sync-all.sh >> ~/clawd/logs/sync.log 2>&1
```

### Pre-commit Hook

Auto-sync on workspace changes:

```bash
# ~/clawd/.git/hooks/pre-commit
#!/bin/bash
cd ~/clawd/skills/workspace-sync
./scripts/sync-all.sh
```

## Troubleshooting

### Permission Denied

```bash
chmod 600 ~/.ssh/id_rsa
```

### Rsync Connection Failure

Check Pi is reachable:

```bash
ping raspberrypi.local
ssh pi@raspberrypi.local
```

### Git Push Rejected

Pull and merge first:

```bash
git pull --rebase
git push
```

## Safety

- **Always test with `--dry-run` first**
- **Secrets are excluded by default** (see `config/sync-exclude.txt`)
- **Backups are not automatic** - Consider external backup strategy
- **Conflicts require manual resolution** - Review carefully before pushing