How to Migrate From an Older Harness Version Using the Doctor Command in Claude-Code-Harness

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.

--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 through 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).

--residue

The --residue flag executes 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 through 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 files. These remain internally compatible but require verification for runtime parity. The system maintains timestamped backups such as .opencode/skills.backup.<ts> 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.

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 to repair OpenCode file structures. Review timestamped backups matching .opencode/*.backup.<ts> 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 through doctor.go#L129. This routine verifies binary version compatibility, confirms the presence of harness.toml, and validates JSON syntax in 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. 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. Only consider purging after explicit confirmation and with verified backups of both ~/.harness-mem/ and project .harness-mem/state/ directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}