Migrating to OmniDev

This guide walks you through migrating an existing repository that uses provider-specific configuration files (.claude, .opencode, AGENTS.md, .mcp.json, etc.) to OmniDev’s unified approach.

Prerequisites

• An existing repository with provider-specific files like:
  • .claude/ - claude configuration
  • .opencode/ - OpenCode configuration
  • AGENTS.md, CLAUDE.md, or similar instruction files
  • .cursor/ - Cursor AI configuration
  • .mcp.json - MCP server configurations
  • Custom skills, commands, or agents defined in provider directories

Migration Steps

1) Install OmniDev

npm install -g @omnidev-ai/cli

Or with Bun:

bun install -g @omnidev-ai/cli

Verify installation:

omnidev --version

2) Initialize OmniDev

Run the init command in your repository root:

omnidev init

This creates:

• OMNI.md - Your project instructions (source of truth)
• omni.toml - Configuration file
• .omni/ - Runtime directory (automatically gitignored)

3) Migrate project instructions

Consolidate provider-specific instructions into OMNI.md:

If you have existing instruction files like:

• CLAUDE.md
• AGENTS.md
• .cursor/rules

Move the project-level content (not provider-specific details) to OMNI.md:

# My Project

## Project Description
A web application for managing tasks with real-time collaboration.

## Conventions
- Use TypeScript strict mode
- Follow the existing code style
- Write tests for all business logic

## Architecture
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: PostgreSQL

What NOT to migrate to OMNI.md:

• File tree structures (agents can discover this themselves)
• Provider-specific tool configurations
• Skills, commands, and agents (these become capabilities)

4) Migrate capabilities

If you have custom skills, commands, or agents in provider directories, convert them to OmniDev capabilities.

Create a local capabilities directory

mkdir -p capabilities

Move skills/commands to capabilities

For example, if you have custom skills in .claude/skills/:

# Create a capability for your custom tools
mkdir -p capabilities/my-project-tools

Create capabilities/my-project-tools/capability.toml:

[capability]
id = "my-project-tools"
name = "My Project Tools"
version = "1.0.0"
description = "Tools for my project"

See Creating Capabilities for detailed documentation on capability structure.

Register your local capability

Add it to omni.toml:

[capabilities.sources]
my-project-tools = "file://./capabilities/my-project-tools"

[profiles.default]
capabilities = ["my-project-tools"]

5) Migrate MCP servers

If you have .mcp.json or MCP configurations in provider directories, move them to omni.toml:

Before (.mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
    }
  }
}

After (omni.toml):

[mcp.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]

See MCP Servers for detailed configuration.

6) Update .gitignore

Add OmniDev-managed files and remove old provider files from version control:

# OmniDev runtime
.omni/
omni.local.toml

# Provider-specific files (now generated by OmniDev)
CLAUDE.md
AGENTS.md
.cursor/rules
.cursor/.cursorrules
.cursor/mcp.json
.mcp.json

# Old provider directories (if migrating away)
.claude/
.opencode/

Important: Keep OMNI.md and omni.toml in version control!

7) Remove old provider files

After verifying your migration, clean up old files:

# Remove old instruction files (these will be regenerated)
git rm --cached CLAUDE.md AGENTS.md

# Remove old MCP configs (now in omni.toml)
git rm --cached .mcp.json
git rm --cached .cursor/mcp.json

# Optional: Remove old provider directories entirely
# (Only do this after moving all custom capabilities)
# git rm --cached .claude/
# git rm --cached .opencode/

8) Run your first sync

Generate provider files from your new configuration:

omnidev sync

This will:

1. Fetch any external capabilities
2. Process your local capabilities
3. Generate CLAUDE.md, AGENTS.md, and other provider files from OMNI.md
4. Embed capability rules and docs into provider files
5. Generate provider-specific MCP configurations

9) Verify setup

omnidev doctor

This checks:

• Configuration validity
• Capability availability
• Provider file generation
• MCP server configurations

Example migration

Before - Old structure:

my-project/
├── .claude/
│   ├── skills/
│   │   └── deploy.ts
│   └── instructions.md
├── .cursor/
│   ├── rules
│   └── mcp.json
├── CLAUDE.md
├── AGENTS.md
└── .mcp.json

After - OmniDev structure:

my-project/
├── capabilities/
│   └── my-project-tools/
│       └── capability.toml
├── .omni/              # gitignored
├── OMNI.md             # source of truth
├── omni.toml           # configuration
├── omni.lock.toml      # auto-generated
├── CLAUDE.md           # generated, gitignored
├── AGENTS.md           # generated, gitignored
└── .gitignore          # updated

Common migration scenarios

Scenario 1: Using Cursor with .cursorrules

If you have .cursor/.cursorrules or .cursor/rules:

1. Copy project-specific content to OMNI.md
2. Add .cursor/rules and .cursor/.cursorrules to .gitignore
3. Run omnidev sync to regenerate them

Scenario 2: Multiple providers

If you’re already using multiple providers (Claude Code, Cursor, etc.):

1. Consolidate shared instructions into OMNI.md
2. Put provider-specific capabilities in separate capability packages
3. Use profiles to enable different capabilities per provider:

[capabilities.sources]
shared-tools = "file://./capabilities/shared"
claude-specific = "file://./capabilities/claude"
cursor-specific = "file://./capabilities/cursor"

[profiles.claude]
capabilities = ["shared-tools", "claude-specific"]

[profiles.cursor]
capabilities = ["shared-tools", "cursor-specific"]

Scenario 3: Team migration

For teams migrating together:

1. One person performs the migration

2. Commit OMNI.md, omni.toml, and updated .gitignore

3. Team members run:

   npm install -g @omnidev-ai/cli
   omnidev sync

4. Old provider files are regenerated automatically

Troubleshooting

Provider files not generated

Run omnidev doctor to check configuration. Ensure your active profile has capabilities enabled.

MCP servers not working

Verify MCP configuration in omni.toml matches your previous setup. Check logs with:

OMNIDEV_DEBUG=1 omnidev sync

Capabilities not loading

Check that:

1. Capability sources are registered in omni.toml
2. Capabilities are enabled in your active profile
3. File paths are correct (use absolute paths or ./ prefix for local files)

Migration Skill

You can use this skill definition to help AI agents guide users through the migration process:

See migration SKILL.md for the skill definition.

Copy this skill to your .claude/skills/, .cursor/, or other provider directory to enable migration assistance.

Next steps

• Add external capabilities from the ecosystem
• Create custom capabilities for your team
• Use profiles for different contexts
• Configure MCP servers for enhanced tools