Skip to Content
ReferenceVersion Migration

Version Migration

How to move between Navigator versions and keep your project config in step with the installed plugin. This page covers the upgrade process — for the full per-version log, see the CHANGELOG  and the releases/ notes.

v7 → v8

v8.0.0 “In Process” moves the hook runtime into Claude Code as a mod: the same ops, in-process, on Claude Code 2.1.287 or newer, with the v7 Python dispatcher kept as the fallback for older versions, blocked mods, or an op that crashes three times in a session. Config and state are unchanged — .agent/.nav-config.json and .agent/.nav-runtime-state.json are shared by both runtimes, so nothing migrates. New: the /nav pane, the status band, the Pilot theme (/theme → Pilot), and a truthful update notice at session start (TASK-81). See the v8.0.0 release notes .

Upgrade steps

  1. claude plugin update navigator@navigator-marketplace.
  2. Restart Claude Code. The plugin manifest now registers the mod; skill paths are cached at session start.
  3. On Claude Code ≥ 2.1.287 nothing else: the mod owns every op. On an older Claude Code the Python runtime keeps running exactly as in v7 — no feature is lost, only the pane and band.
  4. Optional: /theme → Pilot; /nav to open the pane.

Rolling back to v7

claude plugin install navigator@7.9.0 and restart. State and config are compatible in both directions.

v6 → v7

v7.0.0 “Hooks as Runtime” replaces the nine individual v6 hook scripts with a single dispatcher (hooks/nav_dispatch.py) that routes op modules across 13 Claude Code events. Behaviors that v6 mandated as prose in CLAUDE.md (workflow gating, loop exit rules, intent briefs, and so on) are now ops with config off-switches in .agent/.nav-config.json. Runtime state moves to a single file, .agent/.nav-runtime-state.json (schema 2, atomic writes), and the dispatcher is fail-open — a crash never blocks the session. See the v7.0.0 release notes  for the full change list.

Upgrade steps

  1. /plugin update navigator (or install fresh).
  2. Restart Claude Code. The manifest hook set changed, and skill paths are cached at session start — without a restart the v6 hooks stay registered.
  3. Config migrates additively on first run: your v6 blocks in .agent/.nav-config.json are preserved, and the v7 blocks (dispatcher, tier1, stop_completion, the *_hook toggles) are added with safe defaults. Missing blocks always default safe — no manual config surgery required.
  4. Opt in to the new blocking features if you want them: they ship off. Set tier1.enabled for instant answers, and stop_completion.enabled plus stop_completion.continue_enabled for the completion gate.

Rolling back to v6

The additive-only config migration makes rollback safe by design:

  1. claude plugin install navigator@6.18.1.
  2. Restart Claude Code (re-registers the v6 manifest hook set).
  3. Optionally remove the v7-only config blocks — purely cosmetic, v6 ignores them.
  4. .agent/.nav-runtime-state.json is inert under v6 and can be deleted.

Upgrading the plugin

Run the upgrade skill:

nav-upgrade

or say “upgrade Navigator”. It detects the current version, updates the plugin, verifies the install, and then offers to sync your project CLAUDE.md. Session start only shows a notice when a newer release exists (Auto-Update); nothing updates until you run the command or this skill.

After any mid-session update, restart Claude Code so the new skill paths are loaded — Claude Code caches them at session start.

Syncing CLAUDE.md

The plugin binary and your project config version independently. After upgrading the plugin, bring the project config forward:

nav-sync-claude

or say “sync CLAUDE.md” / “update my CLAUDE.md”. It rewrites the managed sections of CLAUDE.md to match the installed version while preserving your customizations (project-specific standards, conventions, notes). nav-upgrade calls nav-sync-claude as one of its steps, so a normal upgrade keeps both in sync.

What version drift means

Version drift is when the installed plugin is ahead of (or behind) what your project config references:

SignalMeaning
Plugin newer than CLAUDE.mdConfig missing newer features — run nav-sync-claude
Docs reference unknown config keys.nav-config.json behind schema — sync or re-init
Skill renamed but old name in docsStale cross-references — sync resolves them

Resolve drift by running nav-sync-claude. The authoritative version source is the plugin manifest, not CLAUDE.md.

Notable deprecations

  • Multi-Claude shell scripts → native Workflows (removed in v7.9.0). The shell-based orchestration, the nav-multi and nav-install-multi-claude skills, the templates and the multi_agent config block are gone (deprecated since v6.15.0). Use Claude Code’s native Workflows and the Agent tool, or Pilot, for parallel and multi-phase work. A stale multi_agent block in an existing config is ignored.
  • Skill renames (v6.14.0): nav-update-claude → nav-sync-claude, nav-task-mode → nav-workflow. No backwards-compat aliases; update any saved references.

Upgrade checklist

  1. Run the command from the session-start notice, or nav-upgrade.
  2. Restart Claude Code after a mid-session update.
  3. Run nav-sync-claude if prompted, to clear version drift.
  4. Confirm .nav-config.json keys match the new schema.
  5. Start a session and verify the version banner.

For the full release history and per-version migration notes, consult the CHANGELOG and releases/ directory in the repository.

TroubleshootingCommunity