syncode

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 43 Open GitHub ↗

Syncode — an adapter-based CLI for syncing AI agent configs across repos

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# syncode - Agent Configuration Manager

[![npm version](https://badge.fury.io/js/%40donnes%2Fsyncode.svg)](https://www.npmjs.com/package/@donnes/syncode)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Stop fighting with AI agent configurations.** Sync your Claude Code, Cursor, Windsurf, OpenCode, and VSCode settings across machines and projects with a single command.

The era of AI-powered coding is here, but managing multiple AI assistants is a mess. `syncode` solves this.

## Why syncode?

**The Problem:** You use Cursor at work, Claude Code for side projects, and want to try Windsurf or Roo Code. Each has its own config format and setup. Keeping 17+ AI agents in sync is manual hell.

**The Solution:** `syncode` is your single source of truth for AI agent configurations.

## Features

- 🤖 **17+ AI Agents** - Claude Code, Cursor, Windsurf, OpenCode, VSCode, GitHub Copilot, Roo Code, Goose, Gemini CLI, Amp, Kilo Code, Kiro CLI, Trae, Codex, Antigravity, Clawdbot, Droid
- 🔄 **Smart Sync** - Automatic detection and sync with smart defaults per agent
- 🔗 **Symlinks & Copy** - Symlinks for live sync, copy for Claude (preserves cache)
- 📦 **Version Control** - Git-based workflow for your AI configurations
- 🛡️ **Safe Operations** - Automatic backups before any changes
- 🖥️ **Machine Setup** - Opinionated development dependencies for macOS/Linux
- 🌍 **Cross-Platform** - macOS, Linux (Windows coming soon)

## Quick Start

### Option 1: npx (No Install Required)

```bash
npx @donnes/syncode new
```

### Already Have a Repo?

```bash
syncode init
```

### Option 2: Global Install

```bash
# Install globally
npm install -g @donnes/syncode

# Or using bun
bun install -g @donnes/syncode

# Initialize
syncode new
```

## Usage

### Initialize a New Repo

```bash
syncode new
```

This will:
- Auto-detect installed AI agents (17+ agents supported)
- Let you select which agents to sync
- Create a git repository for your configs
- Import your existing configs
- Set up smart sync defaults (symlinks for most, copy for Claude, Gemini, etc.)

### Initialize from an Existing Repo

```bash
syncode init
```

This will:
- Prompt for the repo URL and local storage path
- Clone the repo if needed
- Let you choose which agents to sync
- Save configuration to `~/.syncode/config.json`

### Sync Agents Config

```bash
syncode sync
```

Choose direction:
- **Import**: Copy configs from system to repo (before committing changes)
- **Export**: Sync configs from repo to system (on new machines)

### Check Status

```bash
syncode status
```

Shows:
- Which agents are synced
- Sync method (symlink vs copy)
- Git status
- Option to run full machine status

### Machine Dependencies

```bash
syncode machine deps
```

Install opinionated development dependencies for your machine:
- **Unified script**: `install.sh` with curl-based installs where possible
- **Curl-installed**: bun, fnm, uv, atuin, zoxide, fzf, opencode
- **Package manager fallback**: ripgrep, fd, eza, gh, lazygit, go, rbenv, biome, aws-cli, bob
- **macOS only**: OrbStack, Raycast, opencode-desktop (via Homebrew casks)

This is a boilerplate file that gets copied to your repo root during `syncode new`. Edit it to customize the tools for your workflow.

### Machine Status

```bash
syncode machine status
```

Shows comprehensive machine setup status:
- Platform and package manager detection
- Repository and git status
- Dependency file presence
- Quick health check for your development environment

### Push to Remote

```bash
syncode push
```

Push your config changes to the remote repository:
- Detects uncommitted changes
- Optionally commits changes with a message
- Pushes to the configured remote branch

## Supported Agents

| Agent | Config Path | Sync Method | Auto-Detect |
|-------|-------------|-------------|-------------|
| **Amp** | `~/.config/amp` | Symlink | ✅ Yes |
| **Antigravity** | `~/.gemini/antigravity` | Copy | ✅ Yes |
| **Claude Code** | `~/.claude` | Copy | ✅ Yes |
| **Clawdbot** | `~/.clawdbot` | Symlink | ✅ Yes |
| **Codex** | `~/.codex` | Symlink | ✅ Yes |
| **Cursor** | `~/Library/Application Support/Cursor/User` | Symlink | ✅ Yes |
| **Droid** | `~/.factory` | Symlink | ✅ Yes |
| **Gemini CLI** | `~/.gemini` | Copy | ✅ Yes |
| **GitHub Copilot** | `~/.copilot` | Copy | ✅ Yes |
| **Goose** | `~/.config/goose` | Symlink | ✅ Yes |
| **Kilo Code** | `~/.kilocode` | Symlink | ✅ Yes |
| **Kiro CLI** | `~/.kiro` | Symlink | ✅ Yes |
| **OpenCode** | `~/.config/opencode` | Symlink | ✅ Yes |
| **Roo Code** | `~/.roo` | Symlink | ✅ Yes |
| **Trae** | `~/.trae` | Symlink | ✅ Yes |
| **VSCode** | `~/Library/Application Support/Code/User` | Symlink | ✅ Yes |
| **Windsurf** | `~/.codeium/windsurf` | Symlink | ✅ Yes |

## Configuration

Global configuration is stored at `~/.syncode/config.json`:

```json
{
  "version": "1.0.0",
  "repoPath": "~/.syncode/repo",
  "remote": "https://github.com/<username>/configs.git",
  "agents": ["opencode", "claude", "cursor", "windsurf"],
  "features": {
    "autoSync": false,
    "backupBeforeExport": true,
    "smartSyncDefaults": true
  }
}
```

## Repository Structure

```
~/.syncode/repo/
├── .git/
├── .gitignore
├── install.sh
├── README.md
├── .agents/            # Shared skills (symlinked)
│   └── skills/
└── configs/
    ├── amp/               # Symlinked
    ├── antigravity/       # Copy sync
    ├── claude/            # Copy sync (preserves cache)
    ├── clawdbot/          # Symlinked
    ├── codex/             # Symlinked
    ├── cursor/            # Symlinked
    ├── droid/             # Symlinked
    ├── gemini-cli/        # Copy sync
    ├── github-copilot/    # Copy sync
    ├── goose/             # Symlinked
    ├── kilo/              # Symlinked
    ├── kiro-cli/          # Symlinked
    ├── opencode/          # Symlinked
    ├── roo/               # Symlinked
    ├── trae/              # Symlinked
    ├── vscode/            # Symlinked
    └── windsurf/          # Symlinked
```

## Usage Examples

### Daily Workflow

```bash
# Edit your AI agent configs normally
# Example: ~/.config/opencode/opencode.json
# Example: ~/.agents/skills/my-helper.md
# Changes are synced via symlinks automatically

# Check what changed
syncode status

# Import changes to repo
syncode sync
# Select "Import"

# Push to remote (commits and pushes in one command)
syncode push

# Pull changes from remote
syncode pull
```

## Commands

- `syncode new` - Initialize a new agent config repository
- `syncode init` - Initialize from an existing agent config repository
- `syncode sync` - Sync agent configs (import or export)
- `syncode status` - Show status of synced agents
- `syncode push` - Push config changes to git remote
- `syncode pull` - Pull config changes from git remote
- `syncode machine deps` - Install machine dependencies (install.sh)
- `syncode machine status` - Show full machine setup status
- `syncode --version` - Show version
- `syncode help` - Show help message

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/donnes/syncode.git
cd syncode

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Link locally
bun link
```

### Running Tests

```bash
# Type check
bun run typecheck

# Build
bun run build
```

## Platform Support

| Platform | Status | Notes |
|----------|--------|-------|
| macOS | ✅ Fully Supported | Primary development platform |
| Linux | ✅ Fully Supported | Tested on Ubuntu, Arch |
| Windows | 🚧 Planned | Coming soon |

## Requirements

- Node.js >= 20.0.0 or Bun >= 1.0.0
- Git (for repository management)
- macOS or Linux

## Troubleshooting

### Configuration not found

```bash
# Run initialization
syncode new
# Or connect to an existing repo
syncode init
```

### Symlinks not working

```bash
# Check configuration health
syncode status

# Re-export configs
syncode sync
# Select "Export"
```

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

## License

## Support

- 📖 [Documentation](https://github.com/donnes/syncode#readme)
- 🐛 [Report Issues](https://github.com/donnes/syncode/issues)
- 💬 [Discussions](https://github.com/donnes/syncode/discussions)
- 📦 [npm Package](https://www.npmjs.com/package/@donnes/syncode)

---

**Made with ❤️ for developers**

syncode

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README