code-modernization

What it is

Code Modernization is a Claude Code plugin by Anthropic. You point it at a legacy codebase and it produces four things: an understanding of what the system is and does, a plan you approve, the modernized code, and proof that the new code behaves like the old. It works with any language and supports three kinds of move. An uplift moves to a newer version of the same technology, such as .NET Framework to .NET 8, Java 8 to 17, or Spring Boot 2 to 3. A transform rewrites in another technology one module at a time. A reimagine rebuilds on a new architecture. It never edits your legacy source. Commands write only to analysis/<name>/ and modernized/, and each one refreshes a shareable one-page analysis/<name>/REPORT.html. The workflow starts at the front door, /code-modernization:modernize. It records your intent in INTENT.md, and every later command reads that file. The path then runs through these steps: - preflight: environment readiness, five human questions, a build smoke test and a check for missing source - assess: inventory, complexity, debt, security and a recommended pattern - map: dependencies, data flow, entry points and business flows, as an interactive map - extract-rules: Given/When/Then rule cards with file:line citations, each re-checked by a second agent - review: a person confirms or corrects the rules that look wrong - brief: a phased plan; nothing is built until it is approved - build: uplift, transform or reimagine - verify: the proof - harden: a security scan with a reviewed patch you apply yourself A person decides at six points, and the plugin never decides them for you. The proof is built from evidence a script can check, not from the model's opinion. modernize-verify does the following: - reruns the test suite from clean - runs old and new code on the same inputs and compares every byte, with only declared fields masked - invents at least ten new inputs - checks that the tests can fail, using a canary break - requires every critical (P0) rule to be backed by a test that actually ran - confirms the source is untouched scripts/proof_pack.py then computes one verdict per module: PROVEN, PARTLY PROVEN or NOT PROVEN. If the old system cannot run locally, the best possible verdict is PARTLY PROVEN. The plugin was run headlessly on public codebases including AWS CardDemo (COBOL), Eclipse Jetty, osCommerce, AngularJS RealWorld, JPetStore, beets, Spring PetClinic and AWStats, plus a booby-trapped codebase built to test its safety measures. Analyzed code is treated as untrusted input, and discovered secrets are masked. The plugin includes specialist agents and an early-access live progress pane. It sends optional usage telemetry made only of whole numbers, which can be turned off.

Who it's for

• Teams modernizing legacy codebases in any language (e.g. COBOL, Java, PHP, Perl, Python 2, AngularJS, C)
• Engineers doing version upgrades such as Java 8 to 17, Spring Boot 2 to 3 or .NET Framework to newer .NET
• Organizations planning a rewrite or rebuild that need a steering-committee-approved phased plan
• Engineering leads and sponsors who need evidence that the new code behaves like the old
• Teams that only want to understand a legacy system (assessment, map, business rules, plan) without rebuilding it
• Teams surveying and ranking many legacy systems via a portfolio assessment

Requirements

Setup

1. Install the plugin

   With Claude Code installed, install the plugin from the official marketplace.

   textCopy

   /plugin install code-modernization@claude-plugins-official

2. Add workspace permissions (recommended)

   Create a .claude/settings.json in the workspace. It denies edits to the legacy source and allows edits to the outputs. Preflight checks for the deny rule. If legacy/<name> is a symlink made by --source, also allow reading its target and deny edits to its real path.

   jsonCopy

   {
     "permissions": {
       "allow": ["Read(**)", "Edit(analysis/**)", "Edit(modernized/**)"],
       "deny": ["Edit(/legacy/**)"]
     }
   }

3. Optional: enable the live progress pane

   Start Claude Code with early-access function hooks enabled. Without the flag nothing changes.

   bashCopy

   CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

Examples

/code-modernization:modernize

/code-modernization:modernize-preflight <name> --source <path to your code>
/code-modernization:modernize-status <name>       # where am I, and what is next: run it any time

--prompt "/code-modernization:modernize-verify billing"