Upgrade Guide

Keep ContextVault up to date with the latest features and improvements.

Your Documents Are Safe

Upgrades never delete or modify your vault documents. Only the instructions, commands, and hooks are updated.

Understanding ContextVault Components

ContextVault has two layers that can be upgraded independently:

Component Location What It Contains
Global Installation ~/.claude/ CLAUDE.md, 25 slash commands, hooks, global vault
Project Installation ./.claude/ + ./CLAUDE.md Project instructions, project vault

Complete Upgrade Process

Follow these steps to fully upgrade ContextVault:

Step 1: Check Your Current Version

In Claude Code, run:

/ctx-status

Note your current version number.

Step 2: Upgrade Global Installation

This updates the core ContextVault system on your machine.

macOS / Linux

curl -sL https://ctx-vault.com/install | bash

Windows PowerShell (Run as Administrator)

irm https://ctx-vault.com/install.ps1 | iex
What Gets Updated

NOT touched: Your global vault documents (~/.claude/vault/G*.md)

Step 3: Restart Claude Code

After upgrading the global installation, you must restart Claude Code to load the new instructions.

# Close Claude Code completely, then reopen it
# Or if using CLI:
claude
Important

Don't skip this step! Claude Code caches instructions at session start. A restart ensures the new CLAUDE.md and commands are loaded.

Step 4: Upgrade Project Installation

Navigate to each project that uses ContextVault and upgrade its local files:

cd /path/to/your/project

# In Claude Code, run:
/ctx-upgrade

This updates:

Project Vault Untouched

Your project documents (./.claude/vault/P*.md) are never modified during upgrade.

Step 5: Verify the Upgrade

/ctx-status

Confirm the new version is displayed and all components are healthy.

/ctx-changelog

Review what's new in the version you just installed.

Quick Reference

# COMPLETE UPGRADE CHECKLIST
# ─────────────────────────────────────────

# 1. Check current version
/ctx-status

# 2. Upgrade global (run in terminal, not Claude Code)
curl -sL https://ctx-vault.com/install | bash   # macOS/Linux
# or
irm https://ctx-vault.com/install.ps1 | iex     # Windows

# 3. Restart Claude Code
#    Close and reopen the application

# 4. Upgrade each project (in Claude Code)
cd /path/to/project
/ctx-upgrade

# 5. Verify
/ctx-status
/ctx-changelog

Upgrading Multiple Projects

If you have several projects using ContextVault:

  1. Upgrade global installation once
  2. Restart Claude Code once
  3. Run /ctx-upgrade in each project individually
# After global upgrade and restart:

cd ~/projects/project-a
/ctx-upgrade

cd ~/projects/project-b
/ctx-upgrade

cd ~/projects/project-c
/ctx-upgrade

Troubleshooting Upgrades

Commands not recognized after upgrade

Cause: Claude Code hasn't reloaded the commands.

Fix: Restart Claude Code completely (close all windows/terminals).

Hooks not triggering

Cause: settings.json may have old hook format.

Fix: Re-run the installer which regenerates hook configs.

Version still shows old number

Cause: Reading cached CLAUDE.md.

Fix: Ensure you restarted Claude Code after the global upgrade.

/ctx-upgrade fails

Cause: Missing or corrupted project files.

Fix: Re-initialize the project:

/ctx-init

This recreates project structure while preserving existing vault documents.

Downgrading (If Needed)

To install a specific older version, download from GitHub releases:

# View available releases
https://github.com/ahmadzein/ContextVault/releases

# Install specific version (replace TAG with version)
curl -sL https://raw.githubusercontent.com/ahmadzein/ContextVault/TAG/install-contextvault.sh | bash
Downgrade Warning

Older versions may not support features used in newer vault documents. Only downgrade if you encounter critical issues with the latest version.

Staying Updated

Check for updates periodically: