OpenCode Sync

Sync your OpenCode configuration, sessions, and data across multiple machines using a private GitHub repository.

Features

• Sync Everything - Config, sessions, messages, credentials, prompts, and more
• Multi-Machine Support - Safely sync across laptops, VMs, and servers simultaneously
• Conflict Resolution - Vector clocks detect conflicts, three-way merge resolves them
• Encrypted Credentials - AES-256-GCM encryption for sensitive data
• Auto-Sync - Syncs on startup, on file changes (5s debounce, 30s max), and every 5 minutes
• Offline-Friendly - Works offline, syncs when reconnected
• Atomic Updates - Uses Git's compare-and-swap for safe concurrent access

Installation

Step 1: Install the package in your OpenCode config directory:

# Linux/macOS
cd ~/.config/opencode && npm install oc-sync

# Windows (PowerShell)
cd $HOME\.config\opencode; npm install oc-sync

Step 2: Register the plugin in opencode.json (in config directory):

{
  "plugin": ["oc-sync"]
}

Step 3: Configure your GitHub token (see Configuration below)

Step 4: Restart OpenCode

Using an AI coding agent? See LLM Installation Guide for step-by-step prompts.

Note: OpenCode uses XDG paths on all platforms. See Sync Paths for platform-specific locations.

What Gets Synced

Category	Data	Default
Config	opencode.json, agents, commands, modes, tools, themes	✅ Enabled
State	Model selections, prompt history, stashed prompts	✅ Enabled
Credentials	OAuth tokens, MCP auth (encrypted)	✅ Enabled
Sessions	Session metadata and history	✅ Enabled
Messages	Conversation messages and parts	✅ Enabled
Projects	Project configurations	✅ Enabled
Todos	Task lists and session diffs	✅ Enabled

How It Works

Vector Clocks for Conflict Detection

Each machine maintains a logical timestamp. When syncing:

1. Equal - Both in sync, no action needed
2. Local Ahead - Safe to push
3. Remote Ahead - Need to pull
4. Concurrent - Both changed, needs merge

Three-Way Merge

When conflicts occur:

1. Find common ancestor (last synced version)
2. Compute diffs from ancestor to local and remote
3. If diffs don't overlap -> auto-merge
4. If diffs overlap -> apply conflict strategy

Conflict Strategies

Configure in opencode-sync.json:

• auto-merge (default) - Attempt automatic merge
• local-wins - Keep local changes on conflict
• remote-wins - Keep remote changes on conflict
• newest-wins - Keep whichever is newer
• ask - Prompt for resolution

Configuration

1. Create a GitHub Personal Access Token with repo scope
2. Set environment variable:

export GITHUB_TOKEN=ghp_your_token_here

3. Start OpenCode - the plugin automatically creates a private repo for sync storage

See Configuration Guide for all options.

Security

• Credentials are encrypted with AES-256-GCM before upload
• Encryption key is derived from your passphrase using PBKDF2
• The repository is created as private (not public)
• Token is stored locally, never uploaded
• Atomic commits with compare-and-swap prevent race conditions

Documentation

Guide	Description
Configuration	All configuration options
Architecture	Code structure and modules
Sync Architecture	Sync triggers, batching, data categories
Sync Paths	OpenCode file locations by platform
Development Setup	Local development environment
Publishing	npm release process
LLM Installation	Instructions for AI coding agents
TODO	Future improvements

License

AGPL-3.0