Migration Guide

This guide covers all migration paths for oh-my-claudecode. Find your current version below.

Unreleased: Team MCP Runtime Deprecation (CLI-Only)
v3.5.3 → v3.5.5: Test Fixes & Cleanup
v3.5.2 → v3.5.3: Skill Consolidation
v2.x → v3.0: Package Rename & Auto-Activation
v3.0 → v3.1: Notepad Wisdom & Enhanced Features
v3.x → v4.0: Major Architecture Overhaul

Unreleased: Team MCP Runtime Deprecation (CLI-Only)

TL;DR

omc_run_team_start/status/wait/cleanup are now hard-deprecated at runtime. Calls return:

{
  "code": "deprecated_cli_only",
  "message": "Legacy team MCP runtime tools are deprecated. Use the omc team CLI instead."
}

Use CLI commands instead:

omc team [N:agent-type] "<task>"
omc team status <team-name>
omc team shutdown <team-name> [--force]
omc team api <operation> --input '<json>' --json

`omc ask` env alias sunset (Phase-1 compatibility)

OMC_ASK_* is now canonical for advisor execution. Phase-1 accepts OMX_ASK_ADVISOR_SCRIPT and OMX_ASK_ORIGINAL_TASK with deprecation warnings. Planned hard sunset for alias removal: 2026-06-30.

How to Migrate

Replace MCP runtime tool calls with CLI equivalents.
Update skills/prompts from /omc-teams ... to omc team ... syntax.
Legacy Team MCP runtime is now opt-in only (not enabled by default). If you enable it manually, treat responses as deprecation-only compatibility output.

Example mapping

# Old (deprecated runtime path)
mcp__team__omc_run_team_start(...)
mcp__team__omc_run_team_status({ job_id: ... })
mcp__team__omc_run_team_wait({ job_id: ... })
mcp__team__omc_run_team_cleanup({ job_id: ... })

# New (CLI-first)
omc team 2:codex "review auth flow"
omc team status review-auth-flow
omc team shutdown review-auth-flow --force
omc team api list-tasks --input '{"team_name":"review-auth-flow"}' --json

v3.5.3 → v3.5.5: Test Fixes & Cleanup

TL;DR

Maintenance release fixing test suite issues and continuing skill consolidation from v3.5.3.

What Changed

Test Fixes:

Delegation-enforcer tests marked as skipped (implementation pending)
Analytics expectations corrected for agent attribution
All remaining tests now pass cleanly

Skill Consolidation:

Continued cleanup from v3.5.3
Removed deprecated cancel-* skills (use /cancel instead)
Final skill count: 37 core skills

Migration Steps

No breaking changes - All functionality preserved
Test suite now runs cleanly with npm run test:run
Deprecated skills removed (already replaced in v3.5.3)

For Developers

If you were depending on deprecated cancel-* skills, update to use the unified /cancel command which auto-detects the active mode.

v3.5.2 → v3.5.3: Skill Consolidation

TL;DR

8 deprecated skills have been removed. The unified /cancel and /omc-setup commands replace them.

Removed Skills

The following skills have been completely removed in v3.5.3:

Removed Skill	Replacement
`cancel-autopilot`	`/oh-my-claudecode:cancel`
`cancel-ralph`	`/oh-my-claudecode:cancel`
`cancel-ultrawork`	`/oh-my-claudecode:cancel`
`cancel-ultraqa`	`/oh-my-claudecode:cancel`
`omc-default`	`/oh-my-claudecode:omc-setup --local`
`omc-default-global`	`/oh-my-claudecode:omc-setup --global`
`planner`	`/oh-my-claudecode:plan`

What Changed

Before v3.5.3:

/oh-my-claudecode:cancel-ralph      # Cancel ralph specifically
/oh-my-claudecode:omc-default       # Configure local project
/oh-my-claudecode:planner "task"    # Start planning

After v3.5.3:

/oh-my-claudecode:cancel            # Auto-detects and cancels any active mode
/oh-my-claudecode:omc-setup --local # Configure local project
/oh-my-claudecode:plan "task"       # Start planning (includes interview mode)

New Features

New skill: /learn-about-omc

Analyzes your OMC usage patterns
Provides personalized recommendations
Identifies underutilized features

Plan skill now supports consensus mode:

/oh-my-claudecode:plan --consensus "task"  # Iterative planning with Critic review
/oh-my-claudecode:ralplan "task"           # Alias for plan --consensus

Migration Steps

No action required - The unified /cancel command already worked in v3.5
Update any scripts that reference removed commands
Re-run /omc-setup if you want to update your CLAUDE.md configuration

Skill Count

v3.5: 42 skills
v3.5.3: 37 skills (8 removed, 3 added)

v2.x → v3.0: Package Rename & Auto-Activation

TL;DR

Your old commands still work! But now you don't need them.

Before 3.0: Explicitly invoke 25+ commands like /oh-my-claudecode:ralph "task", /oh-my-claudecode:ultrawork "task"

After 3.0: Just work naturally - Claude auto-activates the right behaviors. One-time setup: just say "setup omc"

Project Rebrand

The project was rebranded to better reflect its purpose and improve discoverability.

Project/brand name: oh-my-claudecode (GitHub repo, plugin name, commands)
npm package name: oh-my-claude-sisyphus (unchanged)

Why the difference? The npm package name oh-my-claude-sisyphus was kept for backward compatibility with existing installations. The project, GitHub repository, plugin, and all commands use oh-my-claudecode.

NPM Install Command (unchanged)

npm i -g oh-my-claude-sisyphus@latest

What Changed

Before (2.x): Explicit Commands

You had to remember and explicitly invoke specific commands for each mode:

# 2.x workflow: Multiple commands, lots to remember
/oh-my-claudecode:ralph "implement user authentication"       # Persistence mode
/oh-my-claudecode:ultrawork "refactor the API layer"          # Maximum parallelism
/oh-my-claudecode:planner "plan the new dashboard"            # Planning interview
/oh-my-claudecode:deepsearch "find database schema files"     # Deep search
/oh-my-claudecode:git-master "commit these changes"           # Git expertise
/oh-my-claudecode:deepinit ./src                              # Index codebase
/oh-my-claudecode:analyze "why is this test failing?"         # Deep analysis

After (3.0): Auto-Activation + Keywords

Work naturally. Claude detects intent and activates behaviors automatically:

# 3.0 workflow: Just talk naturally OR use optional keywords
"don't stop until user auth is done"                # Auto-activates ralph-loop
"fast: refactor the entire API layer"               # Auto-activates ultrawork
"plan: design the new dashboard"                    # Auto-activates planning
"ralph ulw: migrate the database"                   # Combined: persistence + parallelism
"find all database schema files"                    # Auto-activates search mode
"commit these changes properly"                     # Auto-activates git expertise

Agent Naming Standard

Agent naming is now strictly descriptive and role-based (for example: architect, planner, analyst, critic, document-specialist, designer, writer, vision, executor).

Use canonical role names across prompts, commands, docs, and scripts. Avoid introducing alternate myth-style or legacy aliases in new content.

Directory Migration

Directory structures have been renamed for consistency with the new package name:

Local Project Directories

Old: .omc/
New: .omc/

Global Directories

Old: ~/.omc/
New: ~/.omc/

Skills Directory

Old: ~/.claude/skills/omc-learned/
New: ~/.claude/skills/omc-learned/

Config Files

Old: ~/.claude/omc/mnemosyne.json
New: ~/.claude/omc/learner.json

Environment Variables

All environment variables have been renamed from OMC_* to OMC_*:

Old	New
OMC_USE_NODE_HOOKS	OMC_USE_NODE_HOOKS
OMC_USE_BASH_HOOKS	OMC_USE_BASH_HOOKS
OMC_PARALLEL_EXECUTION	OMC_PARALLEL_EXECUTION
OMC_LSP_TOOLS	OMC_LSP_TOOLS
OMC_MAX_BACKGROUND_TASKS	OMC_MAX_BACKGROUND_TASKS
OMC_ROUTING_ENABLED	OMC_ROUTING_ENABLED
OMC_ROUTING_DEFAULT_TIER	OMC_ROUTING_DEFAULT_TIER
OMC_ESCALATION_ENABLED	OMC_ESCALATION_ENABLED
OMC_DEBUG	OMC_DEBUG

Command Mapping

All 2.x commands continue to work. Here's what changed:

2.x Command	3.0 Equivalent	Works?
`/oh-my-claudecode:ralph "task"`	Say "don't stop until done" OR use `ralph` keyword	✅ YES (both ways)
`/oh-my-claudecode:ultrawork "task"`	Say "fast" or "parallel" OR use `ulw` keyword	✅ YES (both ways)
`/oh-my-claudecode:ultrawork-ralph`	Say "ralph ulw:" prefix	✅ YES (keyword combo)
`/oh-my-claudecode:planner "task"`	Say "plan this" OR use `plan` keyword	✅ YES (both ways)
`/oh-my-claudecode:plan "description"`	Start planning naturally	✅ YES
`/oh-my-claudecode:review [path]`	Invoke normally	✅ YES (unchanged)
`/oh-my-claudecode:deepsearch "query"`	Say "find" or "search"	✅ YES (auto-detect)
`/oh-my-claudecode:analyze "target"`	Say "analyze" — routes to debugger/architect agent	✅ YES (keyword route)
`/oh-my-claudecode:deepinit [path]`	Invoke normally	✅ YES (unchanged)
`/oh-my-claudecode:git-master`	Say "git", "commit", "atomic commit"	✅ YES (auto-detect)
`/oh-my-claudecode:frontend-ui-ux`	Say "UI", "styling", "component", "design"	✅ YES (auto-detect)
`/oh-my-claudecode:note "content"`	Say "remember this" or "save this"	✅ YES (auto-detect)
`/oh-my-claudecode:cancel-ralph`	Say "stop", "cancel", or "abort"	✅ YES (auto-detect)
`/oh-my-claudecode:omc-doctor`	Invoke normally	✅ YES (unchanged)
All other commands	Work exactly as before	✅ YES

Magic Keywords

Include these anywhere in your message to explicitly activate behaviors. Use keywords when you want explicit control (optional):

Keyword	Effect	Example
`ralph`	Persistence mode - won't stop until done	"ralph: refactor the auth system"
`ralplan`	Iterative planning with consensus	"ralplan: add OAuth support"
`ulw` / `ultrawork`	Maximum parallel execution	"ulw: fix all type errors"
`plan`	Planning interview	"plan: new API design"

ralph includes ultrawork:

ralph: migrate the entire database
    ↓
Persistence (won't stop) + Ultrawork (maximum parallelism) built-in

No keywords? Claude still auto-detects:

"don't stop until this works"      # Triggers ralph
"fast, I'm in a hurry"             # Triggers ultrawork
"help me design the dashboard"     # Triggers planning

Natural Cancellation

Say any of these to stop:

"stop"
"cancel"
"abort"
"nevermind"
"enough"
"halt"

Claude intelligently determines what to stop:

If in ralph-loop     → Exit persistence loop
If in ultrawork      → Return to normal mode
If in planning       → End planning interview
If multiple active   → Stop the most recent

No more /oh-my-claudecode:cancel-ralph - just say "cancel"!

Migration Steps

Follow these steps to migrate your existing setup:

1. Uninstall Old Package (if installed via npm)

npm uninstall -g oh-my-claudecode

2. Install via Plugin System (Required)

# In Claude Code:
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

Note: npm/bun global installs are no longer supported. Use the plugin system.

3. Rename Local Project Directories

If you have existing projects using the old directory structure:

# In each project directory
mv .omc .omc

4. Rename Global Directories

# Global configuration directory
mv ~/.omc ~/.omc

# Skills directory
mv ~/.claude/skills/omc-learned ~/.claude/skills/omc-learned

# Config directory
mv ~/.claude/omc ~/.claude/omc

5. Update Environment Variables

Update your shell configuration files (.bashrc, .zshrc, etc.):

# Replace all OMC_* variables with OMC_*
# Example:
# OLD: export OMC_ROUTING_ENABLED=true
# NEW: export OMC_ROUTING_ENABLED=true

6. Update Scripts and Configurations

Search for and update any references to:

Package name: oh-my-claudecode → oh-my-claudecode
Agent names: Use the mapping table above
Commands: Use the new slash commands
Directory paths: Update .omc → .omc

7. Run One-Time Setup

In Claude Code, just say "setup omc", "omc setup", or any natural language equivalent.

This:

Downloads latest CLAUDE.md
Configures 32 agents
Enables auto-behavior detection
Activates continuation enforcement
Sets up skill composition

Verification

After migration, verify your setup:

Check installation:
```
npm list -g oh-my-claudecode
```

Verify directories exist:

ls -la .omc/  # In project directory
ls -la ~/.omc/  # Global directory

Test a simple command: Run /oh-my-claudecode:omc-help in Claude Code to ensure the plugin is loaded correctly.

New Features in 3.0

1. Zero-Learning-Curve Operation

No commands to memorize. Work naturally:

Before: "OK, I need to use /oh-my-claudecode:ultrawork for speed..."
After:  "I'm in a hurry, go fast!"
        ↓
        Claude: "I'm activating ultrawork mode..."

2. Delegate Always (Automatic)

Complex work auto-routes to specialist agents:

Your request              Claude's action
────────────────────     ────────────────────
"Refactor the database"   → Delegates to architect
"Fix the UI colors"       → Delegates to designer
"Document this API"       → Delegates to writer
"Search for all errors"   → Delegates to explore
"Debug this crash"        → Delegates to architect

You don't ask for delegation - it happens automatically.

3. Learned Skills (`/oh-my-claudecode:learner`)

Extract reusable insights from problem-solving:

# After solving a tricky bug:
"Extract this as a skill"
    ↓
Claude learns the pattern and stores it
    ↓
Next time keywords match → Solution auto-injects

Storage:

Project-level: .omc/skills/ (version-controlled)
User-level: ~/.claude/skills/omc-learned/ (portable)

4. HUD Statusline (Real-Time Orchestration)

See what Claude is doing in the status bar:

[OMC] ralph:3/10 | US-002 | ultrawork skill:planner | ctx:67% | agents:2 | todos:2/5

Run /oh-my-claudecode:hud setup to install. Presets: minimal, focused, full.

5. Three-Tier Memory System

Critical knowledge survives context compaction:

<remember priority>API client at src/api/client.ts</remember>
    ↓
Permanently loaded on session start
    ↓
Never lost through compaction

Or use /oh-my-claudecode:note to save discoveries manually:

/oh-my-claudecode:note Project uses PostgreSQL with Prisma ORM

6. Structured Task Tracking (PRD Support)

Ralph Loop now uses Product Requirements Documents:

/oh-my-claudecode:ralph-init "implement OAuth with multiple providers"
    ↓
Auto-creates PRD with user stories
    ↓
Each story: description + acceptance criteria + pass/fail
    ↓
Ralph loops until ALL stories pass

7. Intelligent Continuation

Tasks complete before Claude stops:

You: "Implement user dashboard"
    ↓
Claude: "I'm activating ralph-loop to ensure completion"
    ↓
Creates todo list, works through each item
    ↓
Only stops when EVERYTHING is verified complete

Backward Compatibility Note

Note: v3.0 does not maintain backward compatibility with v2.x naming. You must complete the migration steps above for the new version to work correctly.

v3.0 → v3.1: Notepad Wisdom & Enhanced Features

Overview

Version 3.1 is a minor release adding powerful new features while maintaining full backward compatibility with v3.0.

What's New

1. Notepad Wisdom System

Plan-scoped wisdom capture for learnings, decisions, issues, and problems.

Location: .omc/notepads/{plan-name}/

File	Purpose
`learnings.md`	Technical discoveries and patterns
`decisions.md`	Architectural and design decisions
`issues.md`	Known issues and workarounds
`problems.md`	Blockers and challenges

API:

initPlanNotepad() - Initialize notepad for a plan
addLearning() - Record technical discoveries
addDecision() - Record architectural choices
addIssue() - Record known issues
addProblem() - Record blockers
getWisdomSummary() - Get summary of all wisdom
readPlanWisdom() - Read full wisdom for context

2. Delegation Categories

Semantic task categorization that auto-maps to model tier, temperature, and thinking budget.

Category	Tier	Temperature	Thinking	Use For
`visual-engineering`	HIGH	0.7	high	UI/UX, frontend, design systems
`ultrabrain`	HIGH	0.3	max	Complex reasoning, architecture, deep debugging
`artistry`	MEDIUM	0.9	medium	Creative solutions, brainstorming
`quick`	LOW	0.1	low	Simple lookups, basic operations
`writing`	MEDIUM	0.5	medium	Documentation, technical writing

Auto-detection: Categories detect from prompt keywords automatically.

3. Directory Diagnostics Tool

Project-level type checking via lsp_diagnostics_directory tool.

Strategies:

auto (default) - Auto-selects best strategy, prefers tsc when tsconfig.json exists
tsc - Fast, uses TypeScript compiler
lsp - Fallback, iterates files via Language Server

Usage: Check entire project for errors before commits or after refactoring.

4. Session Resume

Background agents can be resumed with full context via resume-session tool.

Migration Steps

Version 3.1 is a drop-in upgrade. No migration required!

npm update -g oh-my-claudecode

All existing configurations, plans, and workflows continue working unchanged.

New Tools Available

Once upgraded, agents automatically gain access to:

Notepad wisdom APIs (read/write wisdom during execution)
Delegation categories (automatic categorization)
Directory diagnostics (project-level type checking)
Session resume (recover background agent state)

v3.3.x → v3.4.0: Parallel Execution & Advanced Workflows

Overview

Version 3.4.0 introduces powerful parallel execution modes and advanced workflow orchestration while maintaining full backward compatibility with v3.3.x.

What's New

1. Ultrapilot: Parallel Autopilot

Execute complex tasks with up to 5 concurrent workers for 3-5x speedup:

/oh-my-claudecode:ultrapilot "build a fullstack todo app"

Key Features:

Automatic task decomposition into parallelizable subtasks
File ownership coordination to prevent conflicts
Parallel execution with intelligent coordination
State files: .omc/state/ultrapilot-state.json, .omc/state/ultrapilot-ownership.json

Best for: Multi-component systems, fullstack apps, large refactoring

2. Swarm: Coordinated Agent Teams

N coordinated agents with atomic task claiming:

/oh-my-claudecode:swarm 5:executor "fix all TypeScript errors"

Key Features:

Shared task pool with atomic claiming (prevents duplicate work)
5-minute timeout per task with auto-release
Scales from 2 to 10 workers
Clean completion when all tasks done

3. Pipeline: Sequential Agent Chaining

Chain agents with data passing between stages:

/oh-my-claudecode:pipeline explore:haiku -> architect:opus -> executor:sonnet

Built-in Presets:

review - explore → architect → critic → executor
implement - planner → executor → tdd-guide
debug - explore → architect → debugger
research - parallel(document-specialist, explore) → architect → writer
refactor - explore → architect-medium → executor-high → qa-tester
security - explore → security-reviewer → executor → security-reviewer-low

4. Unified Cancel Command

Smart cancellation that auto-detects active mode:

/oh-my-claudecode:cancel
# Or just say: "stop", "cancel", "abort"

Auto-detects and cancels: autopilot, ultrapilot, ralph, ultrawork, ultraqa, swarm, pipeline

Deprecation Notice: Individual cancel commands are deprecated but still work:

/oh-my-claudecode:cancel-ralph (deprecated)
/oh-my-claudecode:cancel-ultraqa (deprecated)
/oh-my-claudecode:cancel-ultrawork (deprecated)
/oh-my-claudecode:cancel-autopilot (deprecated)

Use /oh-my-claudecode:cancel instead.

6. Explore-High Agent

Opus-powered architectural search for complex codebase exploration:

Task(
  (subagent_type = "oh-my-claudecode:explore-high"),
  (model = "opus"),
  (prompt = "Find all authentication-related code patterns..."),
);

Best for: Architectural analysis, cross-cutting concerns, complex refactoring planning

7. State Management Standardization

State files now use standardized paths:

Standard paths:

Local: .omc/state/{name}.json
Global: ~/.omc/state/{name}.json

Legacy locations are auto-migrated on read.

8. Keyword Conflict Resolution

When multiple execution mode keywords are present:

Conflict Resolution Priority:

Priority	Condition	Result
1 (highest)	Single explicit keyword	That mode wins
2	Generic "fast"/"parallel" only	Read from config (`defaultExecutionMode`)
3 (lowest)	No config file	Default to `ultrawork`

Explicit mode keywords: ulw, ultrawork Generic keywords: fast, parallel

Users set their default mode preference via /oh-my-claudecode:omc-setup.

Migration Steps

Version 3.4.0 is a drop-in upgrade. No migration required!

npm update -g oh-my-claudecode

All existing configurations, plans, and workflows continue working unchanged.

New Configuration Options

Default Execution Mode

Set your preferred execution mode in ~/.claude/.omc-config.json:

{
  "defaultExecutionMode": "ultrawork"
}

When you use generic keywords like "fast" or "parallel" without explicit mode keywords, this setting determines which mode activates.

Breaking Changes

None. All v3.3.x features and commands continue to work in v3.4.0.

New Tools Available

Once upgraded, you automatically gain access to:

Ultrapilot (parallel autopilot)
Swarm coordination
Pipeline workflows
Unified cancel command
Explore-high agent

Best Practices for v3.4.0

When to Use Each Mode

Scenario	Recommended Mode	Why
Multi-component systems	`ultrapilot`	Parallel workers handle independent components
Many small fixes	`swarm`	Atomic task claiming prevents duplicate work
Sequential dependencies	`pipeline`	Data passes between stages
Single complex task	`autopilot`	Full autonomous execution
Must complete	`ralph`	Persistence guarantee

Keyword Usage

Explicit mode control (v3.4.0):

"ulw: fix all errors"           # ultrawork (explicit)
"fast: implement feature"       # reads defaultExecutionMode config

Natural language (still works):

"don't stop until done"         # ralph
"parallel execution"            # reads defaultExecutionMode
"build me a todo app"           # autopilot

Verification

After upgrading, verify new features:

Check installation:
```
npm list -g oh-my-claudecode
```

Test ultrapilot:

/oh-my-claudecode:ultrapilot "create a simple React component"

Test unified cancel:
```
/oh-my-claudecode:cancel
```

Check state directory:

ls -la .omc/state/  # Should see ultrapilot-state.json after running ultrapilot

v3.x → v4.0: Major Architecture Overhaul

Overview

Version 4.0 is a complete architectural redesign focusing on scalability, maintainability, and developer experience.

What's Coming

⚠️ This section is under active development as v4.0 is being built.

Planned Changes

Modular Architecture
- Plugin system for extensibility
- Core/extension separation
- Better dependency management
Enhanced Agent System
- Improved agent lifecycle management
- Better error recovery
- Performance optimizations
Improved Configuration
- Unified config schema
- Better validation
- Migration tooling
Breaking Changes
- TBD based on development progress
- Full migration guide will be provided

Migration Path (Coming Soon)

Detailed migration instructions will be provided when v4.0 reaches release candidate status.

Expected timeline: Q1 2026

Stay Updated

Watch the GitHub repository for announcements
Check CHANGELOG.md for detailed release notes
Join discussions in GitHub Issues

Common Scenarios Across Versions

Scenario 1: Quick Implementation Task

2.x Workflow:

/oh-my-claudecode:ultrawork "implement the todo list feature"

3.0+ Workflow:

"implement the todo list feature quickly"
    ↓
Claude: "I'm activating ultrawork for maximum parallelism"

Result: Same outcome, more natural interaction.

Scenario 2: Complex Debugging

2.x Workflow:

/oh-my-claudecode:ralph "debug the memory leak"

3.0+ Workflow:

"there's a memory leak in the worker process - don't stop until we fix it"
    ↓
Claude: "I'm activating ralph-loop to ensure completion"

Result: Ralph-loop with more context from your natural language.

Scenario 3: Strategic Planning

2.x Workflow:

/oh-my-claudecode:planner "design the new authentication system"

3.0+ Workflow:

"plan the new authentication system"
    ↓
Claude: "I'm starting a planning session"
    ↓
Interview begins automatically

Result: Planning interview triggered by natural language.

Scenario 4: Stopping Work

2.x Workflow:

/oh-my-claudecode:cancel-ralph

3.0+ Workflow:

"stop"

Result: Claude intelligently cancels the active operation.

Configuration Options

Project-Scoped Configuration (Recommended)

Apply oh-my-claudecode to current project only:

/oh-my-claudecode:omc-default

Creates: ./.claude/CLAUDE.md

Global Configuration

Apply to all Claude Code sessions:

/oh-my-claudecode:omc-default-global

Creates: ~/.claude/CLAUDE.md

Precedence: Project config overrides global if both exist.

FAQ

Q: Do I have to use keywords? A: No. Keywords are optional shortcuts. Claude auto-detects intent without them.

Q: Will my old commands break? A: No. All commands continue to work across minor versions (3.0 → 3.1). Major version changes (3.x → 4.0) will provide migration paths.

Q: What if I like explicit commands? A: Keep using them! /oh-my-claudecode:ralph, /oh-my-claudecode:ultrawork, and /oh-my-claudecode:plan work. Note: /oh-my-claudecode:planner now redirects to /oh-my-claudecode:plan.

Q: How do I know what Claude is doing? A: Claude announces major behaviors: "I'm activating ralph-loop..." or set up /oh-my-claudecode:hud for real-time status.

Q: Where's the full command list? A: See README.md for full command reference. All commands still work.

Q: What's the difference between keywords and natural language? A: Keywords are explicit shortcuts. Natural language triggers auto-detection. Both work.

Need Help?

Diagnose issues: Run /oh-my-claudecode:omc-doctor
See all commands: Run /oh-my-claudecode:omc-help
View real-time status: Run /oh-my-claudecode:hud setup
Review detailed changelog: See CHANGELOG.md
Report bugs: GitHub Issues

What's Next?

Now that you understand the migration:

For immediate impact: Start using keywords (ralph, ulw, plan) in your work
For full power: Read docs/CLAUDE.md to understand orchestration
For advanced usage: Check docs/ARCHITECTURE.md for deep dives
For team onboarding: Share this guide with teammates

Welcome to oh-my-claudecode!

FilesExpand file tree

MIGRATION.md

Latest commit

History

MIGRATION.md

File metadata and controls

Migration Guide

Table of Contents

Unreleased: Team MCP Runtime Deprecation (CLI-Only)

TL;DR

omc ask env alias sunset (Phase-1 compatibility)

How to Migrate

Example mapping

v3.5.3 → v3.5.5: Test Fixes & Cleanup

TL;DR

What Changed

Migration Steps

For Developers

v3.5.2 → v3.5.3: Skill Consolidation

TL;DR

Removed Skills

What Changed

New Features

Migration Steps

Skill Count

v2.x → v3.0: Package Rename & Auto-Activation

TL;DR

Project Rebrand

NPM Install Command (unchanged)

What Changed

Before (2.x): Explicit Commands

After (3.0): Auto-Activation + Keywords

Agent Naming Standard

Directory Migration

Local Project Directories

Global Directories

Skills Directory

Config Files

Environment Variables

Command Mapping

Magic Keywords

Natural Cancellation

Migration Steps

1. Uninstall Old Package (if installed via npm)

2. Install via Plugin System (Required)

3. Rename Local Project Directories

4. Rename Global Directories

5. Update Environment Variables

6. Update Scripts and Configurations

7. Run One-Time Setup

Verification

New Features in 3.0

1. Zero-Learning-Curve Operation

2. Delegate Always (Automatic)

3. Learned Skills (/oh-my-claudecode:learner)

4. HUD Statusline (Real-Time Orchestration)

5. Three-Tier Memory System

6. Structured Task Tracking (PRD Support)

7. Intelligent Continuation

Backward Compatibility Note

v3.0 → v3.1: Notepad Wisdom & Enhanced Features

Overview

What's New

1. Notepad Wisdom System

2. Delegation Categories

3. Directory Diagnostics Tool

4. Session Resume

Migration Steps

New Tools Available

v3.3.x → v3.4.0: Parallel Execution & Advanced Workflows

Overview

What's New

1. Ultrapilot: Parallel Autopilot

2. Swarm: Coordinated Agent Teams

3. Pipeline: Sequential Agent Chaining

4. Unified Cancel Command

6. Explore-High Agent

7. State Management Standardization

8. Keyword Conflict Resolution

Migration Steps

`omc ask` env alias sunset (Phase-1 compatibility)

3. Learned Skills (`/oh-my-claudecode:learner`)