/sync-init

Claude Sync Configuration Wizard

You are helping the user set up claude-sync for cross-device synchronization of their Claude Code sessions.

Mode Detection

First, check the current state to determine which mode to use:

test -f ~/.claude-sync/config.yaml && echo "has_config" || echo "no_config"
test -f ~/.claude-sync/age-key.txt && echo "has_key" || echo "no_key"

Passphrase-Only Mode

If config exists but user wants to re-enter passphrase (wrong passphrase on new device):

• Use AskUserQuestion to ask: "Do you want to re-enter your passphrase? (Use this if you entered the wrong passphrase)"
• If yes, skip to the Encryption Passphrase step - keep existing storage config
• This is equivalent to claude-sync init --passphrase

Full Setup Mode

If no config exists, or user wants to start fresh:

• Run the full wizard below

Prerequisites Check

First, check if claude-sync is installed:

command -v claude-sync

If not installed, tell the user to install it first:

npm install -g @tawandotorg/claude-sync

Configuration Flow

Use AskUserQuestion to gather the following information step by step:

Step 1: Storage Provider

Ask which cloud storage provider they want to use:

• Cloudflare R2 (Recommended) - 10GB free, best for personal use
• AWS S3 - For AWS users
• Google Cloud Storage - For GCP users

Step 2: Provider-Specific Credentials

Based on the provider selected:

For Cloudflare R2:

• Bucket name (suggest: claude-sync)
• Account ID (found in Cloudflare dashboard URL)
• Access Key ID (from R2 API Tokens)
• Secret Access Key

For AWS S3:

• Bucket name
• Region (e.g., us-east-1)
• Access Key ID
• Secret Access Key

For Google Cloud Storage:

• Bucket name
• Project ID
• Ask if they want to use:
  • Default credentials (gcloud auth application-default login)
  • Service account JSON file path

Step 3: Encryption Passphrase

Ask for an encryption passphrase:

• Must be at least 8 characters
• Recommend 12+ characters for security
• Important: The same passphrase must be used on all devices to sync
• The passphrase is never stored - only the derived encryption key

Writing Configuration

After gathering all information, create the config directory and files:

mkdir -p ~/.claude-sync
chmod 700 ~/.claude-sync

Write ~/.claude-sync/config.yaml with the appropriate format:

For R2:

storage:
  provider: r2
  bucket: <bucket_name>
  account_id: <account_id>
  access_key_id: <access_key_id>
  secret_access_key: <secret_access_key>
encryption_key_path: ~/.claude-sync/age-key.txt

For S3:

storage:
  provider: s3
  bucket: <bucket_name>
  region: <region>
  access_key_id: <access_key_id>
  secret_access_key: <secret_access_key>
encryption_key_path: ~/.claude-sync/age-key.txt

For GCS with default credentials:

storage:
  provider: gcs
  bucket: <bucket_name>
  project_id: <project_id>
  use_default_credentials: true
encryption_key_path: ~/.claude-sync/age-key.txt

For GCS with service account:

storage:
  provider: gcs
  bucket: <bucket_name>
  project_id: <project_id>
  credentials_file: <path_to_json>
encryption_key_path: ~/.claude-sync/age-key.txt

Set proper permissions:

chmod 600 ~/.claude-sync/config.yaml

Generate Encryption Key

Run the key generation script with the passphrase:

python3 {{plugin_dir}}/scripts/generate-key.py "<passphrase>" ~/.claude-sync/age-key.txt

Note: If argon2-cffi is not installed, install it first:

pip3 install argon2-cffi

Verify Configuration

Test the connection:

claude-sync status

If this is not the first device and there are existing remote files, verify the passphrase works:

claude-sync pull --dry-run

Success Message

After successful configuration, inform the user:

• Configuration saved to ~/.claude-sync/config.yaml
• Encryption key saved to ~/.claude-sync/age-key.txt
• They can now use /sync-push to upload and /sync-pull to download
• Auto-sync is enabled: changes will be pushed on session end or after 5 minutes of idle time
• Remember the passphrase - use the same one on other devices to sync

Security Notes

• Credentials are stored with 600 permissions (owner read/write only)
• All files are encrypted with age before upload
• The passphrase is never stored - only the derived key
• Cloud storage should be private (API key authenticated)