agentleFS
rubiconrubicon/ai-skills/skills/relocate-session/SKILL.md

relocate-session

Skill1 starsChanged 3 months agoMITView on GitHub

Use when moving a Claude Code session to a different project directory, or when a project directory itself has moved or been renamed. Changing the working directory silently orphans auto-memory, which is keyed to the old path — this carries it across, reports what stays behind, and verifies the result. Triggers on "move this session to", "switch to the X repo", "continue this in another directory", "I renamed the project directory", "change_directory", "my memories stopped loading after I moved".

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If it cannot move, say so and stop.

    line 39
  2. Distinctive:

    Default to copy and say that you are.

    line 55
  3. Very specific:

    Verify, do not assume: If $SRC does not exist, do not conclude there is no memory — find the directory by inspection instead.

    line 120
  4. Very specific:

    If $SRC is absent or empty, there is nothing to carry.

    line 133
  5. Distinctive:

    Run the script that ships with this skill.

    line 138
  6. Very specific:

    Never mv, and never delete anything before the copy has been verified.

    line 166
  7. Very specific:

    No other session shares the source: Run list_sessions and resolve each session's cwd through owner.

    line 174
  8. Very specific:

    Leave MEMORY.md alone. Its lines were merged into the destination, but the source index still describes whatever memory remains at the …

    line 207
  9. Very specific:

    If a session is already running in the destination, say so and offer to send it a context message with mcp__ccd_session_mgmt__send_message.

    line 217
  10. Distinctive:

    Do this last. If the memory copy failed, you have not moved yet.

    line 240
  11. Distinctive:

    Always state these three, briefly.

    line 257

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Relocate Session

change_directory moves a session and its whole conversation history in one call. It does not move auto-memory. Auto-memory lives at ~/.claude/projects/<slugified-cwd>/memory/, so after the move the session reads a different — usually empty — directory and every stored memory silently stops loading. Nothing warns you.

This is the procedure. Its only job is to finish the second half.

0. Check the session can move at all

change_directory refuses outright for a session running in an isolated worktree or on a remote host. Check before doing anything else — otherwise you do the whole memory procedure and then discover the move was never possible.

g=$(git rev-parse --path-format=absolute --git-dir 2>/dev/null)
c=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
if [ -n "$g" ] && [ "$g" != "$c" ]; then
  echo "WORKTREE — this session cannot be relocated."
else
  echo "not a worktree — the session can move."
fi

If it cannot move, say so and stop. Do not reach for request_directory as a substitute: it grants access to a folder, it does not move the session, and it leaves memory keyed where it already was. The user's options are to start a session in the target directory, or to relocate a session that is not in a worktree.

1. Pick the scope and the disposition

Ask both, every time. Never assume either one, even when the move looks routine.

Disposition — what happens to the old memory

DispositionMeaning
Copy (default)Both locations keep the memory. The old one still works.
MoveCopy, verify, then remove the source. Only ever performed as copy-then-remove, never as mv, and only when the gates in step 4b all pass.

Default to copy and say that you are. The asymmetry is the reason: a stray copy leaves a duplicate the user can see and delete, while a wrong move destroys memory that is not in version control, from the one location that was working, with no undo.

The trap that makes move dangerous is not obvious: memory directories are routinely shared. Because memory is keyed to the repo root, every session in that repo — including every worktree session, which never has memory of its own — reads the same directory. "The old path" is very often still in active use by someone else.

Scope — what kind of move this is

ScopeMeaningWhat changes
Session moveThis session continues its work somewhere else. The old path still exists and still gets used.Copy memory. Leave the old memory directory alone — other sessions there still need it.
Project moveThe project directory itself moved or was renamed. Nothing will run at the old path again.Copy memory. The old directory becomes a stale leftover — say so and let the user decide whether to delete it. Never delete it yourself. Other sessions still running at the old path do not follow; see step 5.

Both scopes run the same copy. Only the reporting differs.

2. Resolve both memory directories

The source is the running session's own working directory — with one exception. Derive it; never hardcode a path, and never carry one over from a previous run of this skill.

The exception: memory is keyed to the git repository root. A session sitting in a subdirectory of a repo reads memory from the repo root, not from the subdirectory. A session in a worktree reads it from the main repo root — a worktree never owns memory. Only a path outside any repo owns its own. Resolve this with git and confirm against disk rather than slugging $PWD and trusting the result.

The slug is that absolute path with every character outside [a-zA-Z0-9] replaced by -, including the leading /. Dots, slashes, spaces, underscores and tildes all become -. Illustrative only:

Absolute pathProject directory
/Users/someone/dev/example.com/proj-Users-someone-dev-example-com-proj
/Users/someone/Local Sites/my_app-Users-someone-Local-Sites-my-app

The second row is the one that catches people: a rule that only maps / and . looks correct until a path contains a space, an underscore or a tilde.

slug() { python3 -c 'import re,sys; print(re.sub(r"[^a-zA-Z0-9]","-",sys.argv[1]))' "$1"; }

# The path that owns a directory's memory: the main repo root if it is a worktree,
# otherwise the directory itself. Falls back cleanly outside a git repo.
owner() {
  local r
  r=$(git -C "$1" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
    && dirname "$r" || echo "$1"
}

OLD="$PWD"                   # the session's own cwd — derived, not supplied
NEW="<absolute target path>"  # the only input this skill takes
SRC="$HOME/.claude/projects/$(slug "$(owner "$OLD")")/memory"
DST="$HOME/.claude/projects/$(slug "$(owner "$NEW")")/memory"

Apply owner to both ends. Relocating into a subdirectory or a worktree has the same asymmetry: memory copied to that path's own slug would never be read.

Verified against every memory-bearing project directory on a real machine: the rule holds in 35 of 36 testable cases, and the single exception is a session that had itself been relocated — this bug, showing up in its own evidence.

Verify, do not assume. If $SRC does not exist, do not conclude there is no memory — find the directory by inspection instead. Every transcript records its own cwd:

grep -l -F "\"cwd\":\"$OLD\"" "$HOME"/.claude/projects/*/*.jsonl | head

A session that has already been relocated keeps its transcripts in the directory it started in, so the recorded cwd and the directory name legitimately disagree. Trust the directory that actually holds the memory/ files.

3. No memory at the source? Skip it

If $SRC is absent or empty, there is nothing to carry. Say one line and move on to step 5. No ceremony.

4. Copy — never move, never overwrite

Run the script that ships with this skill. Pass it the two directories:

"$SKILL_DIR/scripts/carry-memory.sh" "$SRC" "$DST"

($SKILL_DIR is the base directory reported when the skill loads.)

It copies only — never moves, never overwrites. It reports every collision and keeps the destination's file, appends to MEMORY.md only the index lines the destination lacks, checksum-verifies every copy, prints source=N destination=N copied=N collisions=N, and short-circuits when the two paths are the same directory or the source has no memory.

A non-zero exit means the copy did not verify. Do not relocate the session — report it.

Why this is a script and not inline code. Skill text is rendered with the invocation's argument substituted for the shell's zero positional parameter (dollar-zero). An inline awk script referencing that variable therefore reaches you with the argument pasted in where the field variable should be — malformed, silently producing no merged index, while an existence-only check still reports success. That is silent memory-index loss in exactly the scenario this skill exists to prevent. Code referencing dollar-zero must live in a file. Do not move it back into the prose. (This paragraph avoids writing the variable literally for the same reason.)

Report the collision list and the counts verbatim.

4b. Only if the disposition is move: remove the source

Never mv, and never delete anything before the copy has been verified. All four gates must pass. If any fails, keep the source, say which gate failed, and treat the result as a copy.

  1. Verification was clean. No MISSING: line in step 4, and the destination count is at least the source count. A failed copy plus a deletion is data loss.
  2. Skip every file that collided. A collision means the destination already had a different file under that name and kept its own. Deleting the source copy destroys the only version of that memory. Collided files stay put — say so.
  3. No other session shares the source. Run list_sessions and resolve each session's cwd through owner. If any other session resolves to the same owner as the source, do not delete: they are reading that directory. Remember that worktree sessions resolve to the repo root, so a repo with worktrees almost always fails this gate.
  4. The user confirmed the deletion, after seeing the file list from gate 2.

The commonest reason to want a move is "I started this session in the wrong project." In that case only the memories this session created are pollution — everything the old project had before belongs to it and must stay. Do not delete the whole copied set. List the source files with modification times, separate the ones that predate this session's work, and confirm the shorter list:

find "$SRC" -maxdepth 1 -name '*.md' -exec stat -f '%Sm  %N' -t '%Y-%m-%d %H:%M' {} \;

(stat -f is the BSD/macOS form; stat -c '%y %n' on GNU.)

# Only the files that were verifiably copied AND did not collide.
for f in "$SRC"/*.md; do
  b=$(basename "$f")
  [ "$b" = "MEMORY.md" ] && continue                      # index is merged, never deleted
  [ -e "$DST/$b" ] || { echo "KEPT (not copied): $b"; continue; }
  cmp -s "$f" "$DST/$b" || { echo "KEPT (collided, differs): $b"; continue; }
  rm -- "$f" && echo "removed: $b"
done

cmp is what makes this safe: it deletes a source file only when the destination holds an identical copy. A collided file differs, so it is kept automatically even if gate 2 was misread.

Leave MEMORY.md alone. Its lines were merged into the destination, but the source index still describes whatever memory remains at the source. Prune its entries for removed files rather than deleting the file.

5. Check whether the target is already occupied

mcp__ccd_session_mgmt__list_sessions

If a session is already running in the destination, say so and offer to send it a context message with mcp__ccd_session_mgmt__send_message. Use the real sessionId from list_sessions — the short [abc123] display id from ListAgents is not a valid session_id and the call fails with it.

On a project move, also check for sessions still running at the old path. You cannot relocate another session from here; only it can call change_directory on itself. Offer to message each one so it can move itself.

6. Move the session

mcp__ccd_directory__change_directory  path: <absolute target path>

The working directory only takes effect when the turn ends, so every path used in the same turn must be absolute — relative paths still resolve against the old directory.

This call needs the user's approval and the session pauses on it until they answer. If you are driving another session remotely, that is where it will appear to stall: the memory work is done, the move is queued, and nothing further happens until someone approves the folder in that session's own window. Say so rather than reporting the relocation as complete.

Do this last. If the memory copy failed, you have not moved yet.

Confirm the move actually took effect — the tool's acknowledgement is not proof. It returns "the working directory will move when the current turn ends", which is a promise about the future, not a result. On your next turn:

pwd     # must equal the target; if it does not, the move did not take effect

Observed at least once: approval granted, the call acknowledged, and a turn boundary passed with the session still in the original directory. If pwd disagrees with the target, say the relocation did not happen rather than reporting success — the memory copy will have succeeded regardless, which makes a silent failure here especially easy to miss.

7. Report what did not follow

Always state these three, briefly. They are the parts that surprise people.

  • Repo-local agent state — anything an agent keeps inside the project stays with the project. Detect what is actually there; do not assume a particular name or layout, and do not claim a list like this is complete:

    Directories only, and skip anything git tracks — a tracked dotdir like .github or .claude-plugin is repo content, not agent state. A fixed denylist would always be incomplete; "is it version-controlled" is the distinction that actually holds.

    find "$OLD" -maxdepth 1 -type d -name '.*' -not -name '.git' -not -path "$OLD" -print 2>/dev/null |
      while IFS= read -r d; do
        git -C "$OLD" ls-files --error-unmatch "${d##*/}" >/dev/null 2>&1 || echo "$d"
      done
    [ -d "$OLD/.claude/agent-memory" ] && echo "$OLD/.claude/agent-memory" || true

    Report whatever turns up and let the user decide per item. Leaving it behind is usually correct — it belongs to that project's work, and copying it mixes unrelated contexts. Never move any of it silently.

  • The transcript does follow — this is the one thing the harness carries for you. The session's .jsonl is re-filed under the destination project directory, keeping the entries written before the move, and appending continues there. So the history is resumable and searchable from the new path, and the old project is not left holding it. Confirm it rather than assuming — on the turn after the move:

    find "$HOME/.claude/projects/$(slug "$(owner "$NEW")")" -maxdepth 1 -name '*.jsonl' | head

    Older releases left a partial copy behind at the origin instead of moving cleanly. If you find one, it is a stale prefix of the real transcript — report it, do not delete it.

    Memory is the thing that does not follow. That asymmetry is the whole reason this skill exists: history moves itself, memory does not, and only one of them announces itself.

  • Environment variables — anything the old directory's settings exported is already in the process and cannot be unset by moving. The new directory's settings env applies on top of it, it does not replace it.
  • Everything else switches automatically — project CLAUDE.md, settings, permissions, hooks, MCP servers, and skills all come from the new directory from here on. Say so, so the user knows what changed under them.

Common mistakes

MistakeWhat happens
Calling change_directory and stopping thereMemory silently stops loading. This is the whole reason the skill exists.
Assuming the slug and skipping verificationYou copy into a directory nothing reads, and report success.
mv instead of cpThe old session loses its memory mid-flight. Even a move is copy-verify-remove.
Defaulting to move, or not askingMemory directories are shared across every session in a repo, worktrees included. The deletion hits sessions you never considered.
Deleting a collided source fileThe destination kept its own different file of that name, so the source version is the only copy and it is gone.
cp without -nYou overwrite another session's memory files.
Overwriting MEMORY.mdThe destination's index is destroyed; its memories stay on disk but stop being loaded.
Using the short [abc123] display id as session_idThe message call fails. Use sessionId from list_sessions.
Relative paths in the same turn as the moveThey resolve against the old directory.
Putting code that references dollar-zero in the skill proseThe invocation argument is substituted for it, silently corrupting the code. Keep such code in scripts/.
Verifying a copy by existence aloneA truncated file and a deliberately skipped collision both look like success. Compare checksums.
Slugging $PWD inside a repoIn a subdirectory or a worktree that directory is always empty — memory belongs to the repo root. Resolve with owner first.
Running the whole procedure in a worktree sessionchange_directory refuses at the end. Check step 0 first.
Substituting request_directory for a refused moveIt grants folder access; the session does not move and memory stays keyed to the old root.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.