🦋 Metamorph CLI

The AI Multi-Agent Migration CLI

Metamorph is a CLI tool powered by Mozaik that automates complex architectural shifts and framework migrations in your codebase. Instead of doing it manually, Metamorph spawns a swarm of specialized AI agents that safely refactor your code in an isolated "Shadow Workspace".

Read the Full Documentation | System Architecture

Features

• Project Intelligence Engine (PIE) -- Autonomously detects project architecture, frameworks, and monorepo workspace topologies (Turborepo, pnpm workspaces, npm/yarn workspaces, Lerna).
• Polymorphic Package Manager (PPME) -- Automatically detects and adapts to your chosen package manager (npm, pnpm, yarn, bun) without host process leakage.
• Multi-Agent Concurrency -- Utilizes Mapper, Worker, Reviewer, Integration, and Coordinator agents to migrate code in parallel.
• Zero Risk (Shadow Workspace) -- All migrations happen in an isolated .metamorph/shadow workspace. Your original code is completely untouched until you explicitly approve and apply the changes.
• Shadow Build Verification -- Every migration is validated with your package manager (npm, pnpm, yarn, bun) and verification build inside the shadow workspace before completion.
• Visual Dashboard -- Watch your agents work in real-time through the built-in local dashboard UI.
• Extensive Framework Support -- Easily migrate between popular frontend and backend frameworks.

Installation

Install Metamorph globally via NPM:

npm install -g @nikelyh/metamorph

Prerequisites

• Node.js >= 20
• An LLM provider API key (OpenAI, Anthropic, or compatible). Set it as an environment variable:

  export OPENAI_API_KEY=sk-...

Typical Workflow

1. Start a Migration

Navigate to the root of the project you want to migrate and run:

metamorph run

Metamorph automatically detects your current stack (e.g., Express, React) and prompts you to select the target framework. You can bypass the interactive prompt by passing the source explicitly:

metamorph run --from express

2. Monitor the Agents (Dashboard UI)

Once a migration is running, the AI swarm begins working in the background. To see their real-time progress, open a new terminal in the same directory and run:

metamorph ui

This starts the internal dashboard server and opens a monitoring interface in your default browser. You can specify a port with --port 8080.

3. Review and Apply

After the AI finishes the migration in the isolated Shadow Workspace, you will receive a runId. Apply the completed migration to your actual repository (which automatically creates a new Git branch for safety):

metamorph apply <runId> .

4. Managing Migrations

Discard a run without applying it:

metamorph rollback <runId>

View migration history:

metamorph list

Clear the local database and reset all events:

metamorph reset

Utility Commands

Test the technology detection on your repository without starting a migration:

metamorph detect .

View all available commands and options:

metamorph --help

Supported Migrations

The list of supported architectural shifts is updated frequently as new migration catalogs are added.

See the complete, up-to-date list of all supported frontend and backend framework migrations in the official documentation:

View Supported Migrations

Built with Mozaik. 💖