llm-migrate

Migrate your LLM application to a new model, provider, or platform — for example Anthropic Claude ↔ OpenAI GPT, or a direct API ↔ Amazon Bedrock — with agent-assisted research, a reviewable migration plan, evidence-linked adaptations you accept or reject change by change, and before/after evaluation, all before changing production code.

llm-migrate helps a developer or coding agent inspect an existing Python application, research the source and target models, and decide exactly what a safe migration requires — without editing any application file itself.

Use it when you are:

• upgrading to a newer model generation

• moving between providers, such as Anthropic and OpenAI

• moving between platforms, such as a direct API and Amazon Bedrock

• replacing a deprecated model

• comparing targets for capability, lifecycle, cost, or latency

• validating prompt, tool, structured-output, or invocation changes

The project is local-first and provider-neutral. It does not silently rewrite application files, operate a hosted inference gateway, or promote researched facts into the shared registry without review.

Recommended way to use it

The primary experience is an agent host connected to the llm-migrate MCP server, driving one guided migration run. Codex, Claude Code, or another MCP-capable host supplies the generative models and web/search tools. llm-migrate supplies the scanner, typed research stages, evidence gates, session registry, migration planner, per-file adaptation worklist, per-change review, and evaluation contracts.

One start_migration call creates a run workspace, matches both model identifiers against the reviewed registry (tolerating vague spellings), scans the application, decides whether research is needed and says why, and returns ordered next steps. From there the run is a state machine — get_run_status reports the position and the single next action at any point:

1. Optionally research missing or stale facts with host-supplied agents, independently review every consequential claim, and build an expiring, user-scoped session registry.

2. Work the per-file adaptation worklist: the agent writes adapted prompts and files and submits them with guidance dispositions and evidence-linked annotated changes; unaffected files close in one confirmation call.

3. If the plan has blockers, each becomes a question for you with registry-backed options; the agent presents them verbatim and records your decisions durably.

4. Review every annotated change like a pull request — accept or reject each one; rejections regenerate the deliverable deterministically.

5. Finalize, validate, and finalize again. The first finalize checks the whole deliverable set together and writes the manifest, the report (which opens with an "Action required" list), the change log, and a generated request-shape contract test. You run that test or a BYOK evaluation, the agent records the outcome, and a second finalize records the migration as validated.

If the canonical registry already has fresh coverage, the research request is refused and the agent continues with the reviewed local knowledge. "Live research by default" therefore means always check and research when needed, not "browse even when verified facts already exist."

Related MCP server: FreshStack MCP

Agentic workflow

flowchart TD
    U["Developer + application repository"] --> H["Agent host<br/>Codex, Claude Code, or custom host"]
    H --> M["llm-migrate MCP server"]
    M --> S["start_migration<br/>match models + scan + decide research"]
    S --> K{"Registry knowledge<br/>complete and fresh?"}

    K -- Yes --> W["Per-file adaptation worklist"]
    K -- No --> R["Bounded research request +<br/>generated researcher/reviewer prompts"]
    R --> A["Host-supplied research agents<br/>generative model + web/search"]
    A --> V["Independent evidence reviewer<br/>refetch cited sources"]
    V --> C["Deterministic validation + consensus"]
    C --> O["Immutable, expiring<br/>session registry overlay"]
    O --> W

    W --> B{"Blockers?"}
    B -- Yes --> D["Questions with registry-backed options<br/>presented verbatim; user decides"]
    D --> W
    B -- No --> T["Agent submits adapted prompts/files<br/>with evidence-linked annotated changes"]
    T --> Y["Per-change review<br/>user accepts or rejects each change"]
    Y --> Z["Validation disposition +<br/>consistency-gated finalize"]
    Z --> E{"Run evaluation?"}
    E -- Yes --> X["Source + target evaluation"]
    X --> G["Regression analysis +<br/>bounded optimization"]
    G --> Q["Human review"]
    E -- No --> Q
    Q --> I["Implement migration outside llm-migrate"]

The agent host makes generative calls and writes the adaptations. The MCP server remains the deterministic control and validation layer: it derives worklists, validates fail-closed, stores deliverables under the run's output/, and never modifies the application tree.

Prerequisites

For the recommended guided workflow:

• Python 3.11 or newer

• Git

• a local Python application repository

• an MCP-capable coding agent with a generative model — use the most capable reasoning model your host offers, with extended thinking enabled (for example an Opus- or Fable-class Claude model, or a GPT-5-class model at high reasoning effort). The agent researches, adapts prompts and files with evidence-linked annotations, and relays review decisions; small or fast tiers produce more rejected submissions and retries

• web/search access in that agent host (for research on demand)

• a separate agent or fresh isolated context for evidence review

• the source and target model identifiers as you know them — vague spellings are matched registry-first, and anything ambiguous returns candidates for you to confirm

Provider credentials are not needed for scanning, research validation, planning, adaptation, or reporting. They are only needed when you explicitly run source/target model evaluations. Amazon Bedrock evaluation also requires the optional aws extra and your normal local AWS configuration.

Installation

Easiest: let your coding agent install it

If your coding agent can run shell commands and edit its own MCP configuration (Claude Code, GitHub Copilot, Codex, Cursor, ...), paste this prompt and let it do the setup:

Install the llm-migrate MCP server for me:
1. git clone https://github.com/Athenaxlee/llm-migrate.git into a tools
   directory of your choice (tell me where), or reuse an existing checkout.
2. Inside the checkout, create a Python 3.11+ virtual environment at .venv and
   run: python -m pip install --upgrade pip && python -m pip install .
   (use '.[aws]' instead of '.' if I plan to run Amazon Bedrock evaluations).
3. Verify it works: .venv/bin/llm-migrate registry validate
   (on Windows: .venv\Scripts\llm-migrate registry validate).
4. Register the MCP server in THIS host's own MCP configuration, pointing the
   command at the absolute path of .venv/bin/llm-migrate-mcp
   (Windows: .venv\Scripts\llm-migrate-mcp.exe). Do not change any other
   configuration.
5. Show me the config change and the verification output, and tell me to
   restart/reload so the server is picked up.

For example, on Claude Code the registration step is:

claude mcp add llm-migrate -- /absolute/path/to/llm-migrate/.venv/bin/llm-migrate-mcp

Manual install

git clone https://github.com/Athenaxlee/llm-migrate.git
cd llm-migrate

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .

Windows PowerShell activation:

.venv\Scripts\Activate.ps1

Optional Amazon Bedrock support:

python -m pip install '.[aws]'

Verify the installation:

llm-migrate registry validate
llm-migrate models list

Updating an existing install

When this repository gets new commits and the MCP server is already installed, update the same checkout in place. The MCP configuration keeps pointing at the same .venv executable, so no configuration change is needed:

cd /path/to/llm-migrate              # the checkout your MCP config points at
git pull
.venv/bin/python -m pip install .    # Windows: .venv\Scripts\python -m pip install .
.venv/bin/pip show llm-migrate       # confirm the new version
.venv/bin/llm-migrate registry validate

Then restart or reload your MCP client (or just that server entry): hosts keep the stdio server process running and will not pick up new code until the server restarts. A development install (pip install -e '.[dev]') only needs the git pull and the restart.

Or paste this prompt and let your coding agent do it:

Update my llm-migrate MCP server: find the checkout my MCP configuration points
at, run git pull there, reinstall it into that checkout's .venv with
"python -m pip install .", verify with "llm-migrate registry validate", and
show me the installed version from "pip show llm-migrate". Do not change the
MCP configuration unless the executable path actually moved. Then tell me to
restart/reload the MCP server so the update takes effect.

Connect the MCP server

The installed stdio server is:

llm-migrate-mcp

Each agent host keeps its own MCP registry. Registering the server in one host does not make it available in another — a server added to VS Code's mcp.json serves GitHub Copilot there but is invisible to Claude Code, and vice versa. Register it in every host you use, always pointing at the executable inside the virtual environment:

A generic configuration block (the filename and wrapper syntax vary by host; on Windows the executable is .venv\Scripts\llm-migrate-mcp.exe):

{
  "mcpServers": {
    "llm-migrate": {
      "command": "/absolute/path/to/llm-migrate/.venv/bin/llm-migrate-mcp"
    }
  }
}

Verify in each host after restarting or reloading it: the host's tool list should include start_migration (in Claude Code, claude mcp list shows the server as connected). If the agent says it has no llm-migrate tools, the server is registered in a different host — or the host was not restarted after registration.

The agent host must provide its own generative model and web/search capability. The llm-migrate MCP server does not contain an embedded model or general web search tool, and it never calls an LLM API itself: research, prompt adaptation, and review are done by your coding agent with its own model. Pick that model accordingly (see Prerequisites): the guided workflow is demanding, and a stronger reasoning model with extended thinking finishes it in fewer turns.

Hosts with tight inline-tool budgets can set the environment variable LLM_MIGRATE_TOOLSET=guided on the server process to expose only the 23 guided-workflow tools; the default (full) exposes everything. Production migrations can pass strict=true to start_migration (CLI run start --strict) so unknown evidence, missing invocation facts, incomplete coverage, consistency findings, and a missing validation disposition block delivery instead of warning.

First migration with an agent

Open the application repository in your MCP-capable agent and start the guided run. A useful starting instruction is:

Use the llm-migrate MCP tools to migrate this application.

Application: /absolute/path/to/application
Source: <platform> / <model id as you know it>
Target: <platform> / <model id as you know it>

Start with start_migration and follow its next_steps. When research is
recommended, run it without asking me, with non-interactive background
agents — it needs nothing from me. Ask me before finalizing. Present every
blocker question and review change to me verbatim — do not decide on my
behalf.

Research, when the registry's recorded facts are missing or past their freshness window, runs one researcher and one independent reviewer agent per scope. The generated prompts tell those agents to use web search and page-fetch tools and never a visible browser, and the orchestration guidance runs scopes in parallel, so the stage needs no attention from you. To skip it for a quick pass, add research="skip" to start_migration (CLI --skip-research).

For production migrations, add strict=true: unknown evidence URLs are rejected, missing invocation facts and incomplete prompt coverage block, and finalize refuses to complete cleanly over gaps, findings, undecided changes, or a missing validation disposition.

The run workspace defaults to <application>/.llm-migrate/runs/<run-id>/ (pass output_dir to relocate it) and collects:

Key behaviors during the run:

• Model identifiers are matched registry-first, tolerating Bedrock cross-region prefixes (us.anthropic...), version suffixes (-v1:0), spacing/typos, and loose platform names ("bedrock"). Where the reviewed registry says the target's bare model id is not invocable on demand (for example Claude on Bedrock), start returns the reviewed invocation selectors for you to confirm, and every later surface enforces the selector-qualified id.

• Every prompt task's verbatim_source is the unmodified original, never a proposed adaptation. Submissions must dispose every guidance item (applied / not applicable / declined with a note) and document every edit as an anchored, evidence-linked annotated change, reconciled against the real diff of the decoded runtime values — undocumented or phantom edits are rejected, new files need at least one evidence-linked annotation, and a file that genuinely needs no change is recorded with unchanged=true. Files that only import an SDK incidentally close through one confirm_unaffected call, and submit_adaptations batches submissions in one locked write.

• Blockers are never dead ends: each yields the question to ask you plus registry-backed options with consequences and evidence URLs — retarget, redesign, correction, or an explicit accept that requires your own rationale and is never a default. Decisions whose blocker disappears are reported stale, never silently applied.

• Finalize checks the whole effective deliverable set together: lingering source references (including reviewed aliases of the source model), forbidden bare target ids, mixed selectors, missing target attribution, and undisposed dropped couplings. It also sweeps every scanned application file: a file that still names the source model with no deliverable or recorded review is reported, whatever the scanner failed to trace. A mention you want to keep (documentation, history) is acknowledged with confirm_unaffected(acknowledge_source_references=true) and your own rationale.

• Validation must be evidenced: generated_tests needs your passing test result and its summary line, and byok_evaluation needs the evaluation run artifact bound to the current manifest. An evaluation of an older plan, or a record without evidence, is reported NOT VALIDATED.

• Prompt discovery survives real repository layouts: config paths written relative to the repository root resolve when you scan a subdirectory, Windows-style backslash values and case differences resolve, and simple open(...).read() / Path(...).read_text() loaders are traced. When prompt consumers exist but no prompt file resolved, start_migration lists the candidate files for you to confirm before writing anything; on a live run, add_prompt_sources and confirm_prompt_consumer fix discovery in place instead of forcing a new run.

• Unknowns give directions: each one says why it matters for your application, the exact next call (with the run directory filled in), and what closes it. Where the reviewed registry records conflicting evidence (for example whether adaptive thinking can be disabled on Bedrock), the run emits a small probe script under output/probes/ for you to run with your own credentials; its printed result is recorded with record_observation for this run only and never changes the registry.

• Review has teeth: adapted pricing values are checked against the registry's facts unit-aware (per token / per 1K / per 1M) — a price that departs from the target's recorded price is flagged with its implied factor unless the change cites registry-recorded evidence, and leftover source pricing is flagged stale. A change that depends on a contested registry fact is marked CONTESTED in change review until an observation resolves it, and after the first finalize the run points you at a drafted evaluation instead of letting validation be skipped.

• Research runs by default and hands-free: when facts are missing or past their freshness window, next_steps and get_run_status tell the host to run the research stages now with non-interactive background agents (web search and page-fetch tools, never a visible browser), scopes in parallel, and to ask you first only if you asked to be consulted. A fresh registry (see "Keeping the registry fresh") means no research at all.

• Noise stays out of your way: prompt files referenced only by another model's configuration profile (or unreferenced next to selected siblings) are reported out of scope, unknowns the scan already answers are not raised, and registry guidance whose trigger (structured output, tool use, reasoning) your application never exhibits is pre-marked not applicable with the reason.

MCP tool guide

The tools are grouped in the order an agent normally uses them. Most users drive everything through the guided workflow group; the rest remain available for manual composition.

1. Guided migration workflow (recommended)

2. Understand the application and models

Because the registry is intentionally small, recommend_models only ranks models it knows. Use the research tools when the intended target is missing or its migration-critical facts are stale.

3. Research missing or stale knowledge

Live discovery happens in the agent host, not inside these tools. Research agents receive the bounded request and use the host's generative model and search tools. The reviewer must independently refetch cited sources. See the agent-host workflow for the artifact protocol.

4. Prepare the migration (low-level)

Prompt preparation itself does not call a generative model: the deterministic candidate is the source prompt verbatim, with evidence-linked guidance. The model-authored rewrite belongs to the agent host, and the guided workflow then holds it to dispositions, annotations, and per-change review. That rewrite is deliberately not a hidden core operation.

5. Evaluate and improve

Endpoint configurations name credential environment variables; they never contain credential values. Built-in execution supports direct OpenAI, direct Anthropic, and Amazon Bedrock Converse. Other platforms require an executor supplied by a Python host.

Other interfaces

CLI

Use the CLI for manual operation, automation, artifact inspection, or when an agent host can read and write the stage YAML files but cannot call MCP directly. The guided workflow is mirrored as llm-migrate run start|status|tasks|blockers|decide|submit-prompt|submit-file| confirm-unaffected|record-validation|finalize|review|decide-change, plus llm-migrate models match and llm-migrate research prompts.

llm-migrate --help
llm-migrate run --help
llm-migrate research --help
llm-migrate plan --help
llm-migrate eval --help

The CLI and MCP server are thin interfaces over the same Python service.

Headless Python

A Python host can implement llm_migrate.core.orchestration.AgentRunner and call MigrationService.run_agent_research(...). The host supplies agent calls; the service still owns budgets, retries, resumability, artifacts, and gates.

Agent workflow instructions

docs/agent-research-workflow.md is the agent-neutral workflow used by Codex, Claude Code, or another host. It describes how the host should run research and review. It is not a standalone model or hosted service, and it is not packaged as a separate installed Codex or Claude skill. The MCP server is the primary agent-facing product interface.

Safety and trust

• Research agents receive exact identities and normalized requirements rather than the full repository whenever possible.

• Repository and webpage content is untrusted data and cannot change orchestration instructions, permissions, limits, or schemas.

• A researcher cannot review its own claims.

• Contradictory evidence remains unresolved; majority vote does not make it true.

• Session knowledge is hash-linked, expiring, user-scoped, and visibly session_agent_reviewed or session_unreviewed.

• Only a maintainer-reviewed proposal can change the canonical registry.

• Planning, preparation, and adaptation never rewrite application source files; deliverables live in the run workspace.

• The agent presents blocker questions, options, evidence, and review changes verbatim; the user decides, and an explicit accept requires the user's own rationale.

• Every edit in a deliverable is an anchored, evidence-linked annotated change reconciled against the real diff; serialization tricks cannot hide content from validation or make an unchanged deliverable look adapted.

• The generated contract test is emitted for you to run; the toolkit never executes your application, tests, or provider calls on its own.

research -> evidence -> independent review -> session overlay -> migration plan
                                            \
                                             -> maintainer proposal -> canonical registry

Current scope and limitations

Contributing

Contributions are welcome through reviewed pull requests. Start with CONTRIBUTING.md, follow the evidence requirements in the research policy for registry work, and report security issues privately through SECURITY.md.

Project governance is documented in GOVERNANCE.md, and all participants must follow the Code of Conduct.

Development

python -m pip install -e '.[dev]'
pytest
ruff check .
ruff format --check .
mypy

The repository registry is discovered automatically. To use another registry, pass --registry PATH or set LLM_MIGRATE_REGISTRY to a root containing models/.

Keeping the registry fresh

Freshness windows are short by design (7 days for pricing and lifecycle, 14 for availability, 30 for capabilities and prompt guidance). Maintainers keep them honest with a refetch-only refresh that never edits registry/:

llm-migrate registry refresh-evidence --model claude-sonnet-5

It refetches only the source URLs already recorded in the profile, hashes each page's visible text against the baseline in .registry-proposals/<model>/refresh-evidence.yaml, and reports: unchanged pages that still name the model propose moving checked_at for the categories they support; a page that no longer names the model (a lineup page that dropped a legacy model) vouches for nothing; changed pages are held until you re-verify them (then --rebaseline); a URL with no baseline gets one recorded and proposes nothing; a category the bundle's review put on hold stays held. Promote an approved proposal by hand through the model's bundle, like every other registry change. --no-record produces a read-only report; --output DIR writes it as YAML and Markdown.

Design references:

• Project context

• Architecture

• Research policy

• Development phases

• Adaptation review

License

Copyright © 2026 Athena Li.

Licensed under the Apache License, Version 2.0. See LICENSE.