Skip to main content

Upgrading ContextRelay

ContextRelay is published to npm as @proofofwork-agency/contextrelay and ships prebuilt bundles, so upgrading happens in two steps:

  1. Update the package with your package manager.
  2. Reconcile your project with ctxrelay upgrade so the parts ContextRelay manages on your behalf - the project config, the managed instruction blocks in CLAUDE.md / AGENTS.md, the bare /contextrelay command, and the registered Claude plugin - line up with the new version.

The binaries contextrelay, ctxrelay, and context-relay are interchangeable; this page uses ctxrelay.

Why a separate reconcile step

Updating the npm package only changes the files on disk. It does not touch your .contextrelay/config.json, the managed blocks in your instruction files, or the plugin Claude Code has registered. ctxrelay upgrade is the third flow alongside ctxrelay init (first-time setup) and ctxrelay dev (local source rebuild): it brings the agent-facing surface in line with the package you just installed - safely and idempotently.

Step 1 - Update the package​

Update to the latest release:

npm install -g @proofofwork-agency/contextrelay@latest

Pin to a specific version when you want a controlled bump:

npm install -g @proofofwork-agency/contextrelay@3.x

Confirm the installed version:

ctxrelay --version

Step 2 - Reconcile with ctxrelay upgrade​

From inside your project, run:

ctxrelay upgrade

ctxrelay upgrade reconciles the following, in order, and prints a summary at the end:

  1. Validates the installed version and records the version it applied, so the next run (and ctxrelay doctor) can show the from → to change.
  2. Migrate-merges .contextrelay/config.json. It deep-merges the current defaults into your existing config, so new default keys are added while your explicit values are preserved. Settings you have chosen - coordinator, permissions, activation (auto-connect vs dormant), autonomy, budgets, write-mode - are left exactly as they are. If no project config exists yet, it creates one with defaults, like init.
  3. Refreshes the managed instruction blocks in the CLAUDE.md / AGENTS.md files that already carry a ContextRelay block (your project files plus the conventional global copies and ancestor copies). Each file's state is preserved: a full block is re-rendered as a full block, and a slim (dormant) block stays slim. Only the content inside the managed markers is touched - your own prose outside that region is never altered.
  4. Refreshes the bare /contextrelay command at ~/.claude/commands/contextrelay.md only if it already exists (it exists when you have gone dormant with ctxrelay standalone on). If it is absent, upgrade does not create it.
  5. Re-registers and reinstalls the Claude plugin so Claude Code picks up the new bundles. This step is best-effort: if it fails (for example, Claude Code is not installed or you are offline), upgrade prints a clear remediation instead of failing the whole command.
  6. Prints a summary: the version change (from X → Y, or now at Y), the config keys added, the instruction files refreshed (with full/slim state), the bare-command status, and the plugin status.
Settings are preserved, not reset

Config reconciliation is additive. It adds the new default keys that a release introduces and leaves your explicit choices untouched. It does not reset your coordinator, flip your activation state, or change your permissions. Always read the printed summary so you know exactly what changed before you resume work.

Reload the plugin in a running session

ctxrelay upgrade re-registers the plugin, but a Claude Code session that is already open keeps the previously loaded plugin until you reload it. When the upgrade finishes, run /reload-plugins in your active Claude Code session (or restart it) so the new plugin takes effect. upgrade reminds you of this in its summary.

Preview first with --dry-run​

To see exactly what upgrade would do without writing anything or touching the plugin, run:

ctxrelay upgrade --dry-run

This computes and prints the full plan - config keys that would be added, instruction files that would be refreshed and in which state, bare-command and plugin actions - and performs zero writes. It is the safest way to inspect a bump before applying it.

Flags​

FlagEffect
--dry-runCompute and print the plan only. Writes nothing and runs no plugin install.
--no-pluginSkip the Claude plugin re-register/reinstall step. Use this when Claude Code is not installed or you are offline; config and instruction reconciliation still run.
--instructions <mode>Control how instruction files are handled (see below). Default: refresh.
-h, --helpShow usage.

The --instructions modes:

  • refresh (default) - refresh only the instruction files that already carry a managed block, preserving each file's slim/full state. This is the conservative default: it never adds a block where there isn't one.
  • project / global / both - additionally install blocks where they are missing, the same way init does, for the chosen scope.
  • skip - touch no instruction files at all.
# Refresh existing blocks and also install missing project-scope blocks
ctxrelay upgrade --instructions project

# Reconcile config and plugin only; leave all instruction files alone
ctxrelay upgrade --instructions skip
What upgrade will not do

ctxrelay upgrade never runs git, npm, or release operations; it never changes your coordinator or your activation on/off state; and it never "un-slims" a dormant file (that would silently re-activate a session you intentionally quieted). It also does not rebuild ContextRelay from source - that is ctxrelay dev, for local development checkouts.

Verify the upgrade​

After upgrading, confirm everything is healthy:

ctxrelay status
ctxrelay doctor
  • ctxrelay status prints daemon, session, ledger, and policy state.
  • ctxrelay doctor checks binaries, auth, state, plugin registration, daemon health, and stale locks. Add --no-auth to skip the Claude/Codex auth probes if you only want a quick local check.

Glance at the summary and confirm the coordinator and permissions are still what you expect - see config.json reference and Configure collaboration policy.

Pick up new bundles in a long-running daemon

The ContextRelay daemon can keep using the previously loaded bundle until it is restarted. ctxrelay upgrade does not force-restart the daemon, so to be certain a long-running daemon is on the new code: finish any active turns and handoffs, run ctxrelay kill, then relaunch your agents (ctxrelay claude / ctxrelay codex, or ctxrelay pair). See Daily operation and Troubleshooting and recovery.

Manual fallback (older releases)​

If you are on a ContextRelay release that predates ctxrelay upgrade, you can perform the same reconciliation by hand:

# 1. Re-register and reinstall the Claude plugin
ctxrelay dev        # local development checkout (rebuilds from source)
# or reinstall the shipped plugin for your installed package

# 2. Refresh the managed instruction blocks for your scope
ctxrelay instructions install --scope project    # or: global | both

# 3. Confirm plugin registration, daemon health, and config
ctxrelay doctor

# 4. Restart the daemon when idle so it loads the new bundle
ctxrelay kill       # then relaunch your agents

Then run /reload-plugins in any open Claude Code session, exactly as you would after ctxrelay upgrade.

Use a feature branch for instruction changes

ctxrelay instructions install rewrites the managed block in your committed CLAUDE.md / AGENTS.md. If those files are under version control, review the diff and commit it deliberately (a fix or chore branch + PR), so the change is reviewed rather than slipping in unnoticed. ContextRelay never deletes content outside its own managed markers.

Next steps​