Sync OpenCode data across machines using a private GitHub repository with vector clock conflict resolution
npm install oc-syncSync your OpenCode configuration, sessions, and data across multiple machines using a private GitHub repository.
- 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
Step 1: Install the package in your OpenCode config directory:
``bashLinux/macOS
cd ~/.config/opencode && npm install oc-sync
Step 2: Register the plugin in
opencode.json (in config directory):`json
{
"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
$3
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
$3
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
$3
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 resolutionConfiguration
1. Create a GitHub Personal Access Token with
repo scope
2. Set environment variable:`bash
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.
- 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
| 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 |
AGPL-3.0