Move Claude CLI Projects - MacOS

A developer has released a shell script, mvclaude, that moves a project directory along with its Claude Code CLI context, including session transcripts, project settings, and history. The script handles the encoding of absolute paths into Claude's storage format and offers options to clean or merge existing context at the destination.

| /bin/bash | | set -e | | | | mvclaude — move a project directory AND its Claude Code CLI context with it. | | | | Usage: mvclaude <old directory <new directory | | | | What Claude Code keys off the project path: | | ~/.claude/projects/<encoded-path / session transcripts .jsonl | | ~/.claude.json - "projects" object keyed by the ABSOLUTE path | | trust, allowed tools, per-project MCP servers | | ~/.claude/history.jsonl global prompt history contains cwd | | | | Encoding rule verified in claude v2.1.251 : | | every non-alphanumeric character becomes "-" ^a-zA-Z0-9 - - | | | | if $ -ne 2 ; then | | echo "Usage: mvclaude <old directory <new directory " | | echo "Example: mvclaude ~/old-project ~/new-project" | | exit 1 | | fi | | | | OLD DIR="$1" | | NEW DIR="$2" | | CLAUDE DIR="$HOME/.claude" | | | | --- Validate everything BEFORE touching anything ----------------------------- | | | | OLD ABS=$ cd "$OLD DIR" 2 /dev/null && pwd || true | | if -z "$OLD ABS" ; then | | echo "Error: old directory does not exist: $OLD DIR" | | exit 1 | | fi | | | | if -e "$NEW DIR" ; then | | echo "Error: destination already exists: $NEW DIR" | | exit 1 | | fi | | | | case "$NEW DIR" in | | / NEW PARENT=$ dirname "$NEW DIR" ;; | | NEW PARENT=$ dirname "./$NEW DIR" ;; | | esac | | NEW PARENT ABS=$ cd "$NEW PARENT" 2 /dev/null && pwd || true | | if -z "$NEW PARENT ABS" ; then | | echo "Error: parent of destination does not exist: $NEW PARENT" | | exit 1 | | fi | | NEW ABS="$NEW PARENT ABS/$ basename "$NEW DIR" " | | | | Correct encoding: ALL non-alphanumerics - "-" not just "/" and "." | | encode { printf '%s' "$1" | sed 's/ ^a-zA-Z0-9 /-/g'; } | | OLD ENCODED=$ encode "$OLD ABS" | | NEW ENCODED=$ encode "$NEW ABS" | | | | Claude truncates encodings 200 chars and appends a hash; not handled here. | | if ${ OLD ENCODED} -gt 200 || ${ NEW ENCODED} -gt 200 ; then | | echo "Error: encoded path exceeds 200 chars; Claude hash-truncates these. Aborting." | | exit 1 | | fi | | | | --- Check for existing context at the destination ---------------------------- | | | | SUBDIRS="projects file-history todos shell-snapshots debug" | | | | EXISTING CONTEXT="" | | for subdir in $SUBDIRS; do | | NEW PATH="$CLAUDE DIR/$subdir/$NEW ENCODED" | | if -e "$NEW PATH" ; then | | EXISTING CONTEXT="$EXISTING CONTEXT $subdir" | | fi | | done | | | | if -n "$EXISTING CONTEXT" ; then | | echo "Warning: Claude context already exists for $NEW ABS:" | | for item in $EXISTING CONTEXT; do | | COUNT="" | | if "$item" = "projects" && -d "$CLAUDE DIR/$item/$NEW ENCODED" ; then | | SESSION COUNT=$ find "$CLAUDE DIR/$item/$NEW ENCODED" -maxdepth 1 -name " .jsonl" 2 /dev/null | wc -l | tr -d ' ' | | COUNT=" $SESSION COUNT sessions " | | fi | | echo " - $item$COUNT" | | done | | echo "" | | echo "Options:" | | echo " c Clean out existing context and continue" | | echo " m Merge old context into existing context" | | echo " n Abort default " | | echo "" | | read -p "Choose c/m/N : " -n 1 -r | | echo | | if $REPLY =~ ^ Cc $ ; then | | for item in $EXISTING CONTEXT; do | | rm -rf "$CLAUDE DIR/$item/$NEW ENCODED" | | echo " removed $item" | | done | | elif $REPLY =~ ^ Mm $ ; then | | echo "Will merge contexts..." | | else | | echo "Aborted." | | exit 1 | | fi | | echo "" | | fi | | | | --- 1. Move the real directory FIRST most likely thing to fail ------------- | | | | echo "Moving directory:" | | echo " $OLD ABS" | | echo " - $NEW ABS" | | mv "$OLD ABS" "$NEW ABS" | | echo "" | | | | --- 2. Move / merge the context directories ---------------------------------- | | | | MOVED=0 | | for subdir in $SUBDIRS; do | | OLD PATH="$CLAUDE DIR/$subdir/$OLD ENCODED" | | NEW PATH="$CLAUDE DIR/$subdir/$NEW ENCODED" | | if -d "$OLD PATH" ; then | | if -d "$NEW PATH" ; then | | echo "Merging $subdir/$OLD ENCODED - $subdir/$NEW ENCODED" | | find, not glob: also moves dotfiles | | find "$OLD PATH" -mindepth 1 -maxdepth 1 -exec mv {} "$NEW PATH/" \; | | rmdir "$OLD PATH" 2 /dev/null || rm -rf "$OLD PATH" | | else | | echo "Moving $subdir/$OLD ENCODED - $subdir/$NEW ENCODED" | | mv "$OLD PATH" "$NEW PATH" | | fi | | MOVED=$ MOVED + 1 | | elif -f "$OLD PATH" ; then | | echo "Moving $subdir/$OLD ENCODED - $subdir/$NEW ENCODED" | | mv "$OLD PATH" "$NEW PATH" | | MOVED=$ MOVED + 1 | | fi | | done | | | | if "$MOVED" -eq 0 ; then | | echo "No Claude context found for $OLD ABS" | | else | | echo "Moved $MOVED context location s " | | fi | | echo "" | | | | --- 3. Rewrite path references python: safe with any characters ------------ | | Replaces OLD ABS only when NOT followed by A-Za-z0-9 .- , so moving | | /a/b never rewrites /a/b2, /a/b x, or /a/b.bak /a/b/sub still matches . | | | | echo "Updating path references..." | | python3 - "$OLD ABS" "$NEW ABS" "$CLAUDE DIR" "$NEW ENCODED" <<'PYEOF' | | import json, re, shutil, sys, time | | from pathlib import Path | | | | old, new, claude dir, new encoded = sys.argv 1:5 | | claude dir = Path claude dir | | stamp = time.strftime "%Y%m%d-%H%M%S" | | pat = re.compile re.escape old + r' ? A-Za-z0-9 .- ' | | | | def rewrite p : | | s = p.read text errors="surrogateescape" | | s2 = pat.sub lambda m: new, s | | if s2 = s: | | p.write text s2, errors="surrogateescape" | | return 1 | | return 0 | | | | Session transcripts | | proj = claude dir / "projects" / new encoded | | n = sum rewrite f for f in proj.rglob " .jsonl" if proj.is dir else 0 | | print f" session files updated: {n}" | | | | Global history | | hist = claude dir / "history.jsonl" | | if hist.is file : | | shutil.copy2 hist, hist.with name f"history.jsonl.bak-{stamp}" | | if rewrite hist : | | print " history.jsonl updated backup kept " | | | | ~/.claude.json: per-project trust / allowed tools / MCP servers | | cfg = Path.home / ".claude.json" | | if cfg.is file : | | data = json.loads cfg.read text | | projects = data.get "projects", {} | | if old in projects: | | shutil.copy2 cfg, cfg.with name f".claude.json.bak-{stamp}" | | entry = projects.pop old | | if new in projects: | | entry.update projects new existing destination entry wins | | projects new = entry | | cfg.write text json.dumps data, indent=2 | | print " ~/.claude.json project entry moved backup kept " | | PYEOF | | | | echo "" | | echo "Done: $OLD ABS - $NEW ABS" |