Skip to content

Upgrade

ctx

Upgrade

New versions of ctx may ship updated permissions, CLAUDE.md directives, or plugin hooks and skills.

Claude Code User?

The marketplace can update skills, hooks, and prompts independently: /plugin → select ctx → Update now (or enable auto-update).

The ctx binary is separate: rebuild from source or download a new release when one is available, then run ctx init --force --merge. Knowledge files are preserved automatically.

TL:DR

# Plugin users (Claude Code)
# /plugin → select ctx → Update now
# Then update the binary and reinitialize:
ctx init --force --merge

# From-source / manual users
# install new ctx binary, then:
ctx init --force --merge
# /plugin → select ctx → Update now   (if using Claude Code)

What Changes Between Versions

ctx init generates two categories of files:

Category Examples Changes between versions?
Infrastructure .claude/settings.local.json (permissions), ctx-managed sections in CLAUDE.md and PROMPT.md, ctx plugin (hooks + skills) Yes
Knowledge .context/TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md, ARCHITECTURE.md, GLOSSARY.md, CONSTITUTION.md, AGENT_PLAYBOOK.md No: this is your data

Infrastructure is regenerated by ctx init and plugin updates. Knowledge files are yours and should never be overwritten.

Upgrade Steps

1. Install the New Version

Build from source or download the binary:

cd /path/to/ctx-source
git pull
make build
sudo make install
ctx --version   # verify

2. Reinitialize

ctx init --force --merge
  • --force regenerates infrastructure files (permissions, ctx-managed sections in CLAUDE.md and PROMPT.md).
  • --merge preserves your content outside ctx markers.

Knowledge files (.context/TASKS.md, DECISIONS.md, etc.) are preserved automatically: ctx init only overwrites infrastructure, never your data.

Encryption key: The encryption key lives at ~/.ctx/.ctx.key (outside the project). Reinit does not affect it. If you have a legacy key at .context/.ctx.key or ~/.local/ctx/keys/, copy it manually (see Syncing Scratchpad Notes).

3. Update the ctx Plugin

If you use Claude Code, update the plugin to get new hooks and skills:

  1. Open /plugin in Claude Code.
  2. Select ctx.
  3. Click Update now.

Or enable auto-update so the plugin stays current without manual steps.

4. Review Custom Settings

If you added custom permissions to .claude/settings.local.json beyond what ctx init provides, diff and merge:

diff .claude.bak/settings.local.json .claude/settings.local.json

Manually add back any custom entries that the new init dropped.

5. Verify

ctx status          # context files intact
ctx drift           # no broken references

6. Clean Up

If you made manual backups, remove them once satisfied:

rm -rf .context.bak .claude.bak CLAUDE.md.bak PROMPT.md.bak

What If I Skip the Upgrade?

The old binary still works with your existing .context/ files. But you may miss:

  • New plugin hooks that enforce better practices or catch mistakes;
  • Updated skill prompts that produce better results;
  • New .gitignore entries for directories added in newer versions;
  • Bug fixes in the CLI itself.

The plugin and the binary can be updated independently. You can update the plugin (for new hooks/skills) even if you stay on an older binary, and vice versa.

Context files are plain Markdown: They never break between versions.

The surrounding infrastructure is what evolves.