Auto-Update (auto_update)

Tells you when a newer Navigator release exists and gives you the one command to install it. Navigator never updates itself from a hook.

How it works since v8.0.0 (TASK-81). At session start the mod compares its own version with the latest GitHub release (at most every check_interval_hours, never under PILOT_EXECUTOR) and shows a notice with the command:
claude plugin update navigator@navigator-marketplace
then restart Claude Code — it caches skill paths at session start. “Start my Navigator session” runs the nav-start skill, whose Step 1.5 calls auto_updater.py once and reports its result. In v7.0.0 – v7.9.0 the session-start hook only ran a read-only drift check and the update depended on the model executing the skill, which was not reliable.

Configuration

Add to .agent/.nav-config.json:


{
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 1,
    "curl_fallback": false
  }
}

Key	Default	Behavior
`enabled`	`true`	When `true`, session start checks the latest release and shows the notice; nav-start Step 1.5 applies the update. When `false`, there is no check and no notice; update with the command or `nav-upgrade`.
`check_interval_hours`	`1`	Minimum hours between release checks. Inside the window the last answer is reused, no network call.
`curl_fallback`	`false`	Since v8.3.4. A session with `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` makes Claude Code refuse every plugin fetch, so the check never answers and the notice never fires. With `true`, a refused fetch repeats the same GET through `curl` (same headers, no shell, 3-second cap). Ships off because it is outbound traffic the engine was told to refuse; set it in `.agent/.nav-config.local.json` on the machines that want the notice anyway.

"auto_update": true (the older boolean form) is accepted and means enabled: true with a 1-hour interval.

What session start does

Reads its own version from the plugin manifest (never from claude plugin list inside a hook).
If the interval has elapsed, fetches the GitHub releases list with a 4-second limit; drafts and prereleases are skipped.
If the latest stable release is newer, shows one notice:


Navigator 8.0.0 installed · 8.1.1 available · run: claude plugin update navigator@navigator-marketplace

Nothing is installed. The notice repeats on each session start until you update.

Applying the update

Either:

run claude plugin update navigator@navigator-marketplace, or
say “Start my Navigator session”: nav-start Step 1.5 runs auto_updater.py, which refreshes the marketplace, runs the update, verifies the installed version on disk, and reports the result verbatim. If claude plugin update fails it falls back to uninstall/reinstall.

Then restart Claude Code.

Restart Required (and Why)

Claude Code caches skill definitions at session start. When the plugin is updated mid-session:

Plugin files on disk update correctly
The active session still points at the old cached skill paths
New or updated skills won’t load until you restart

This is Claude Code behavior, not a Navigator bug. Without a restart, old skill versions keep running and you may see “skill not found” errors.

Edge Cases

Situation	Behavior
Network failure or 4 s timeout	No notice, nothing recorded; the next session start checks again.
Rate-limited or malformed API answer	Same as a network failure. `curl_fallback` does not repeat a non-2xx answer.
Fetch refused (`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`)	No notice, nothing recorded, unless `curl_fallback: true`; then the same GET runs through `curl` and the result is handled as above.
Disabled in config	No check, no notice.
Checked recently	The last answer is reused; no network call inside `check_interval_hours`.
Under Pilot (`PILOT_EXECUTOR` set)	No network call, no notice.

Disabling

For manual control over upgrades:


{
  "auto_update": {
    "enabled": false
  }
}

No notices. Run claude plugin update navigator@navigator-marketplace or nav-upgrade when you want to update.

Example


{
  "auto_update": {
    "enabled": true,
    "check_interval_hours": 6
  }
}

Checks for a newer release at most once every 6 hours and shows the notice when one exists.