Updating¶
Check your version¶
Version numbers on this page are illustrative
The current release is the badge at the top of the
README, or the
releases page.
claude-update --check always compares against the live latest.
claude-doctor prints the same version on its first line, and
claude-profiles --version prints just the number.
The version string carries the git description too, so 1.4.0 (v1.4.0-3-gabc1234)
means three commits past the tag, and a -dirty suffix means you have
uncommitted local changes.
Update¶
It checks GitHub for a newer release, runs git pull --ff-only in your
~/.claude-tools checkout, and shows what changed:
installed: 1.4.0 (v1.4.0)
available: 1.5.0 https://github.com/Nandeep2750/claude-profiles/releases/tag/v1.5.0
git pull --ff-only
a1b2c3d -> e4f5g6h
feat: claude-update
docs: updating page
the shell layer changed - run 'exec $SHELL -l' or open a new terminal
That last line matters. Changes under bin/ take effect immediately, because
the shell functions launch the Python core fresh on every call. Changes under
shell/ - new commands, completions, the cd hook - need already-open shells
reloaded. claude-update tells you which kind you just got, so you only restart
when it is actually necessary.
Changes that need your attention¶
Most updates only add things. A few change what an existing command does, and those are listed here so they do not surprise you.
| Version | Change | To keep the old behaviour |
|---|---|---|
| 2.3.0 | Deleting a session, with either claude-clear or claude-prune, also removes file-history/, jobs/ and the other folders named after it. claude-prune gains --orphaned and --traces. Run claude-prune --traces once to clear what older versions left behind. |
nothing to change - the old behaviour left your file contents on disk |
| 2.2.0 | claude-prune no longer counts a session's side files as sessions. Earlier versions listed them and --yes deleted them. |
nothing to change - the old behaviour was a bug |
| 2.1.0 | claude-handoff also moves the session's <session-id>/ directory of tool results and subagent logs. Handoffs made before this release left it in the old profile - claude-doctor lists any that are stranded. |
nothing to change |
| 2.0.0 | claude-handoff moves a session instead of copying it. The source is renamed to <session-id>.jsonl.bak. |
--copy per command, or CLAUDE_HANDOFF_COPY=1 |
The changelog marks every breaking change with a major version bump.
Reloading your shell¶
When claude-update says the shell layer changed, reload any terminal you
already had open. New terminals pick the change up on their own.
Only already-open shells need this
A terminal opened after the update reads the new files at startup. Reloading is only for the ones that were already running.
Safety¶
--ff-only- the update refuses to merge or rebase. If your checkout has diverged it stops rather than creating a merge commit.- Local changes block it. If you have edited anything, it lists what and stops. Commit or stash first.
- Account data is never touched. Updating only pulls
~/.claude-tools. Your profiles, credentials and conversations live in~/.claude-profilesand are not part of the repo.
If you did not install with git¶
only works on a git checkout. If you copied the folder across by hand,
claude-update will say so - re-copy it, or convert to a checkout:
rm -rf ~/.claude-tools
git clone https://github.com/Nandeep2750/claude-profiles.git ~/.claude-tools
sh ~/.claude-tools/install.sh
Reinstalling is safe to run twice. It will not add a second source line to your
rc file, and it never touches account data.
Pinning a version¶
claude-update will then report a newer release available but refuse to pull,
because a detached checkout is not fast-forwardable. Return with
git checkout main.