# How to Migrate From an Older Harness Version Using the Doctor Command in Claude-Code-Harness > Easily migrate from older Harness versions with the harness doctor command. Get a non-destructive compatibility report for plugins, Codex skills, OpenCode, and harness-mem before upgrading. - Repository: [Chachamaru/claude-code-harness](https://github.com/Chachamaru127/claude-code-harness) - Tags: migration-guide - Published: 2026-05-28 --- **Run `harness doctor --migration-report` to generate a non-destructive inventory of compatibility concerns across plugin cache, Codex skills, OpenCode files, and harness-mem state before upgrading.** The `claude-code-harness` project by Chachamaru127 provides a dedicated `harness doctor` sub-command to safely assess migration readiness when upgrading from older versions. This read-only diagnostic tool inspects six critical areas of your installation—from stale plugin caches to persistent memory databases—allowing you to identify and resolve issues without risking data loss. ## Available Migration Assessment Flags The `harness doctor` command supports three independent flags for migration analysis, each implemented in [`go/cmd/harness/doctor.go`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go). ### --migration The `--migration` flag displays a classification table for each hook command, identifying whether it uses **Go** or **shell** implementations. It warns about mixed-mode events that could cause inconsistent behavior during upgrades. According to the source code in [`doctor.go#L60`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L60) through [`doctor.go#L76`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L76), this logic lives in the `runMigrationCheck` function. ### --migration-report The `--migration-report` flag produces a **non-destructive inventory report** of all user-visible migration concerns. When this flag is supplied, the `runDoctor` function (lines 15–71) executes `runMigrationReportCheck`, which enumerates plugin cache state, slash entries, Codex skills, OpenCode files, and `harness-mem` persistence layers. The report format and compatibility rules are documented in [[`docs/onboarding/migration.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/onboarding/migration.md)](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/onboarding/migration.md). ### --residue The `--residue` flag executes [`scripts/check-residue.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/check-residue.sh) to locate remnants of previous v3 migrations that might interfere with current operations. This check is implemented in [`doctor.go#L17`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L17) through [`doctor.go#L28`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L28). ## Understanding the Migration Report The migration report analyzes six major areas that affect upgrade safety. When you invoke `runMigrationReportCheck` via the `--migration-report` flag, the tool inspects the following components: **Claude plugin cache** identifies stale cached plugin versions. The compatibility rule requires updating via Claude Code's plugin manager rather than manual deletion. If rollback is necessary, run `/plugin update claude-code-harness` inside Claude Code. **Claude slash entries** detects missing `harness-*` skill entries that indicate install drift. This is treated as configuration drift rather than unsupported host errors. Resolution requires re-installing the plugin then running `/harness-setup`. **Codex local skills** scans for duplicate front-matter names or old aliases. The safe fallback involves running `scripts/setup-codex.sh --user`, with automatic backups stored in `${CODEX_HOME}/backups/setup-codex`. **Codex symlinks** identifies old symlink installs, particularly problematic on Windows systems. The preferred resolution copies skill directories rather than linking them, achieved by re-running `scripts/setup-codex.sh --user`. **OpenCode files** inspects `.opencode/skills`, plugins, and [`AGENTS.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/AGENTS.md) files. These remain internally compatible but require verification for runtime parity. The system maintains timestamped backups such as `.opencode/skills.backup.` before any modifications. **harness-mem state** examines the memory database that survives across Claude Code and Codex sessions. **Never delete** this database during migration. Preserve both `~/.harness-mem/` and project `.harness-mem/state/` directories. Use `harness mem doctor` for health checks and only purge with explicit confirmation after reviewing the companion contract in [`docs/harness-mem-companion-contract.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/harness-mem-companion-contract.md). ## Step-by-Step Migration Workflow Follow this sequence to safely migrate from an older harness version using the doctor command: 1. **Generate the inventory**: Run `bin/harness doctor --migration-report` to produce the read-only assessment. This command has no side effects and will not modify your data. 2. **Address plugin warnings**: If the report indicates stale plugin cache, update via Claude Code's interface using `/plugin update claude-code-harness`. Do not manually delete cache directories. 3. **Fix Codex duplicates**: Resolve duplicate skills or deprecated symlinks by executing `scripts/setup-codex.sh --user`. Verify backup integrity in `${CODEX_HOME}/backups/setup-codex` before proceeding. 4. **Refresh OpenCode layout**: Run [`scripts/setup-opencode.sh`](https://github.com/Chachamaru127/claude-code-harness/blob/main/scripts/setup-opencode.sh) to repair OpenCode file structures. Review timestamped backups matching `.opencode/*.backup.` if restoration becomes necessary. 5. **Verify harness-mem health**: Execute `harness mem doctor` to receive a JSON health object confirming database integrity. Only consider purge operations if the health check explicitly recommends them and you have confirmed backups. ## Basic Health Checks Without Flags Running `harness doctor` **without any flags** still performs essential validation through the `runBasicChecks` function located at [`doctor.go#L94`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L94) through [`doctor.go#L129`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go#L129). This routine verifies binary version compatibility, confirms the presence of [`harness.toml`](https://github.com/Chachamaru127/claude-code-harness/blob/main/harness.toml), and validates JSON syntax in [`hooks.json`](https://github.com/Chachamaru127/claude-code-harness/blob/main/hooks.json). While these checks do not assess migration-specific concerns, they ensure the harness installation meets baseline operational requirements. ## Summary - **Use `harness doctor --migration-report`** to generate a safe, read-only inventory of migration blockers across six critical areas. - **Never delete `harness-mem` databases** during migration; rely on `harness mem doctor` for health verification instead. - **Resolve Codex issues** with `scripts/setup-codex.sh --user`, which automatically creates backups in `${CODEX_HOME}/backups/setup-codex`. - **Update plugin cache** through Claude Code's `/plugin update claude-code-harness` command, not manual deletion. - **Check for v3 residue** using `harness doctor --residue` to identify legacy artifacts before completing your upgrade. ## Frequently Asked Questions ### Is the migration report safe to run on a production environment? Yes. The `harness doctor --migration-report` command is **entirely read-only** according to the implementation in [`go/cmd/harness/doctor.go`](https://github.com/Chachamaru127/claude-code-harness/blob/main/go/cmd/harness/doctor.go). It generates warnings and summaries without deleting data or modifying configurations, making it safe to execute on active projects to assess upgrade readiness. ### What should I do if the doctor reports a stale plugin cache? Update the cache using Claude Code's built-in plugin manager by running `/plugin update claude-code-harness` inside your Claude Code interface. Do not manually delete cache directories, as this can cause synchronization errors with the harness state. ### How do I handle duplicate Codex skills during migration? Execute `scripts/setup-codex.sh --user` to automatically resolve duplicates and update skill aliases. The script preserves your previous configuration in `${CODEX_HOME}/backups/setup-codex`, allowing you to restore previous states if the update causes issues. ### Can I delete the harness-mem database to fix migration issues? **No.** The documentation and source code explicitly warn against deleting the `harness-mem` database during migration. Instead, run `harness mem doctor` to check database health via the JSON contract defined in [`docs/harness-mem-companion-contract.md`](https://github.com/Chachamaru127/claude-code-harness/blob/main/docs/harness-mem-companion-contract.md). Only consider purging after explicit confirmation and with verified backups of both `~/.harness-mem/` and project `.harness-mem/state/` directories.