Skip to content

README.en.md

Latest commit

 

History

History
129 lines (100 loc) · 4.34 KB

README.en.md

File metadata and controls

129 lines (100 loc) · 4.34 KB
Raw

AI Tool Configuration Sync

npm-version npm-download License typescript node.js vitest tsup

Automated script to migrate Claude configurations to different AI IDE tools

Supported Tools

  • Cursor
  • Claude Code
  • CodeBuddy
  • OpenCode
  • CodeX
  • Gemini CLI
  • IFlow CLI

Quick Start

1. Prepare Configuration

Follow Claude Code Configuration Specification https://code.claude.com/docs/settings

Create ~/.claude directory with the following subdirectories:

  • ~/.claude/commands/ - Custom commands (Markdown format)
  • ~/.claude/skills/ - Skill modules (Markdown format)
  • ~/.claude/CLAUDE.md - Instructions
  • ~/.claude.json - MCP configuration file

2. Quick Start

npm i -g @jl-org/ai-sync

# Interactive execution
ai-sync
# View help
ai-sync --help
? Select tools to migrate (use arrow keys, space to select, enter to confirm):
 ◯  Cursor
 ⬤  Claude Code
 ⬤  OpenCode
 ◯  Gemini CLI
 ◯  IFlow CLI

? Configure to current project (otherwise global config)? (y/N) n
? Auto-overwrite existing files? (y/N) y

Starting migration...
✓ Migrating Commands... (2/2)
✓ Migrating Skills... (1/1)
✓ Migrating MCP... (1/1)

--- Migration Complete ---
Tools: Claude Code, OpenCode
Success: 15
Skipped: 3
Errors: 0

Custom Configuration

You can deeply customize the sync behavior by creating an ai-sync.config.js file in the project root directory

1. Using defineConfig

With defineConfig, you can define new tool configurations or modify existing tool sync logic:

import { defineConfig } from '@jl-org/ai-sync'

export default defineConfig({
  tools: {
    // Define a new tool: test-cli
    'test-cli': {
      name: 'Test CLI',
      // Supported configuration types
      supported: ['commands', 'skills', 'mcp'],
      // Specific transformation logic
      commands: {
        source: '.test-cli/commands',
        format: 'markdown',
        target: '~/.test-cli/commands',
      }
    }
  }
})

Execution Rules

Configuration Transformation Rules

Configuration Type Transformation Description
Commands Claude → Cursor/OpenCode: Direct copy
Claude → Gemini/IFlow: Markdown → TOML automatic conversion
Skills All tools: Direct copy
Instructions CLAUDE.md → tool-specific instruction files: Gemini (GEMINI.md), Codex/OpenCode/Cursor/IFlow (AGENTS.md), CodeBuddy (CODEBUDDY.md)
MCP Claude → Cursor/OpenCode/Gemini/IFlow: Automatic format conversion

Unsupported Configurations

Configuration Type Reason
Rules Only Cursor and Claude Code support a Rules system with file path scoping — other tools lack this feature, making sync impractical. You can use nested AGENTS.md files (e.g. project/src/api/AGENTS.md) as a directory-level scoping alternative
Hooks Hooks implementations are entirely different: Claude Code / Codex / Cursor use JSON + Shell, OpenCode uses TypeScript — formats and execution mechanisms cannot be unified

Path Rules

  • Tool Configuration: Unified use of global Home directory configuration paths, such as ~/.cursor/, ~/.claude/
  • Path Resolution: Support using ~ to represent the user's home directory, automatically handles cross-platform paths
  • Default Directory: Default to using home directory ~ as the configuration detection starting point, with ~/.claude as the sole configuration standard
  • Specified Path: Support specifying custom source and target project directories through command-line parameters or configuration files