openclaw-checkpoint

What this skill does

# OpenClaw Checkpoint Skill

Backup and restore your OpenClaw identity, memory, agents, and configuration across machines.

**Platform:** macOS and Linux only. Windows is not supported.

## Overview

This skill provides disaster recovery for OpenClaw by syncing your workspace and agents to a git repository. It preserves:

- **Identity**: SOUL.md, IDENTITY.md, USER.md (who you and the assistant are)
- **Memory**: MEMORY.md and memory/*.md files (conversation history and context)
- **Cron Jobs**: Scheduled tasks exported to memory/cron-jobs-backup.json (morning briefs, daily syncs, automations)
- **Configuration**: TOOLS.md, AGENTS.md, HEARTBEAT.md (tool setups and conventions)
- **Scripts**: Custom tools and automation you've built
- **Agents**: All agent folders from ~/.openclaw/agents/ (alex, blake, etc.)

**Not synced** (security): API keys (.env.*), credentials, OAuth tokens

## Installation

### Option 1: Git Clone (Recommended)

```bash
# Clone the skill repo
git clone https://github.com/AnthonyFrancis/openclaw-checkpoint.git ~/.openclaw/skills/openclaw-checkpoint

# Copy scripts to tools directory
mkdir -p ~/.openclaw/workspace/tools
cp ~/.openclaw/skills/openclaw-checkpoint/scripts/checkpoint* ~/.openclaw/workspace/tools/
chmod +x ~/.openclaw/workspace/tools/checkpoint*

# Add to PATH (also add to ~/.zshrc or ~/.bashrc for persistence)
export PATH="${HOME}/.openclaw/workspace/tools:${PATH}"

# Run setup wizard
checkpoint-setup
```

### Option 2: Quick Install

```bash
curl -fsSL https://raw.githubusercontent.com/AnthonyFrancis/openclaw-checkpoint/main/scripts/install-openclaw-checkpoint.sh | bash
```

This runs the install script -- review it first if you prefer to inspect before executing.

## Commands

### checkpoint
**Show all available commands and usage examples.**

```bash
checkpoint
```

**What it does:**
- Displays a quick reference of all checkpoint commands with descriptions and examples

**When to use:**
- When you can't remember the exact command name
- Quick reference for available options

### checkpoint-setup
**Interactive onboarding flow for first-time setup.**

```bash
checkpoint-setup
```

**What it does:**
- Guides you through creating a PRIVATE GitHub repository
- Sets up SSH authentication (recommended) or Personal Access Token
- Automatically detects if SSH key is already authorized on GitHub
- Detects agents in `~/.openclaw/agents/` and reports they will be included in backups
- Generates a README.md with recovery instructions and commands
- Commits workspace files within `~/.openclaw/workspace` (secrets excluded via .gitignore)
- Configures automatic backups
- Tests the backup system
- Shows final status

**When to use:**
- First time setting up checkpoint system
- After installing the skill
- After running `checkpoint-reset`
- Recommended starting point for new users

### checkpoint-auth
**Authenticate with GitHub (browser-based).**

```bash
checkpoint-auth
```

**What it does:**
- Option 1: GitHub CLI (opens browser automatically)
- Option 2: Personal Access Token (expires, needs renewal)
- Option 3: SSH Key (recommended - no token expiry)
- Automatically adds GitHub to known_hosts
- Tests authentication after setup

**When to use:**
- Authentication expired or failed
- Switching authentication methods
- Setting up on a new machine

**SSH is recommended** because:
- No token expiration to worry about
- Works reliably without password prompts
- GitHub no longer accepts password authentication for HTTPS

### checkpoint-backup
Save current state to remote repository.

```bash
checkpoint-backup                     # Backup workspace + all agents
checkpoint-backup --workspace-only    # Backup workspace only (skip agents)
checkpoint-backup --agents-only       # Backup agents only (skip workspace/cron)
checkpoint-backup --agent alex        # Backup only the 'alex' agent (+ workspace)
```

**What it does:**
- Backs up OpenClaw cron jobs to `memory/cron-jobs-backup.json` (requires `openclaw` CLI and running gateway)
- Copies agent folders from `~/.openclaw/agents/` into `agents/` in the workspace repo (strips nested `.git` dirs)
- Normalizes home-directory paths (`$HOME` -> `{{HOME}}`) for cross-machine portability
- Commits all changes in ~/.openclaw/workspace
- Pushes to origin/main
- Shows commit hash and timestamp

**Agent backup details:**
- Auto-detects agents in `~/.openclaw/agents/` (e.g., alex, blake)
- Each agent folder is copied to `agents/<name>/` in the backup repo
- Nested `.git` directories are removed to avoid submodule issues
- If no agents exist, skips gracefully with an info message
- Uses `rsync --exclude='.git'` when available, falls back to `cp -r` + manual `.git` removal

**Cron job backup details:**
- Runs `openclaw cron list --json` to export all scheduled tasks
- Strips runtime state, keeps only configuration (name, schedule, target, payload)
- Non-blocking: if the CLI or gateway is unavailable, checkpoint-backup continues without cron backup

**Flags:**
- `--workspace-only` — skip agent backup
- `--agents-only` — skip workspace and cron backup, only back up agents
- `--agent <name>` — back up a single named agent only

**When to use:**
- Before switching computers
- After significant changes (new memory, updated SOUL.md)
- Any time you want to ensure changes are saved

### checkpoint-schedule
Set up automatic backups with configurable frequency.

```bash
checkpoint-schedule 15min      # Every 15 minutes
checkpoint-schedule 30min      # Every 30 minutes
checkpoint-schedule hourly     # Every hour (default)
checkpoint-schedule 2hours     # Every 2 hours
checkpoint-schedule 4hours     # Every 4 hours
checkpoint-schedule daily      # Once per day at 9am
checkpoint-schedule disable    # Turn off auto-backup
```

**What it does:**
- macOS: Creates launchd plist for reliable background backups
- Linux: Adds cron job for scheduled backups
- Logs all activity to ~/.openclaw/logs/checkpoint.log

**When to use:**
- First time setup: `checkpoint-schedule hourly`
- Change frequency: `checkpoint-schedule 15min`
- Stop backups: `checkpoint-schedule disable`

### checkpoint-status
Check backup health and status.

```bash
checkpoint-status
```

**What it shows:**
- Last backup time and commit
- Whether local is behind remote
- Uncommitted changes
- Agent backup status (which agents are backed up, which are missing)
- Auto-backup schedule status
- Recent backup activity log

**When to use:**
- Before switching machines (verify synced)
- Troubleshooting backup issues
- Regular health checks

### checkpoint-restore
Restore state from remote repository, with checkpoint selection and first-time onboarding.

```bash
checkpoint-restore                    # Select from recent checkpoints (interactive)
checkpoint-restore --latest           # Restore most recent checkpoint (skip selection)
checkpoint-restore --force            # Discard local changes before restoring
checkpoint-restore --workspace-only   # Restore workspace only (skip agents)
checkpoint-restore --agents-only      # Restore agents only (skip workspace/cron)
checkpoint-restore --agent alex       # Restore only the 'alex' agent
```

**What it does:**
- **First-time users:** Launches interactive restore onboarding flow
  - Guides you through GitHub authentication (SSH, GitHub CLI, or PAT)
  - Lets you specify your existing backup repository
  - Verifies access and restores your checkpoint
  - Handles merge/replace options if local files exist
  - Shows available checkpoints to pick from (if the repo has more than one commit)
  - Offers to restore cron jobs from backup
  - Offers to restore agents from backup
- **Returning users:** Shows a list of the 10 most recent checkpoints to choose from
  - Pick the latest or any older checkpoint to restore
  - Current checkpoint is marked in the list
  - Restoring an older checkpoint warns that the next backup will overwrite newer remote checkpoints
  - Use `--latest` flag to skip the interactive selection and restore the