Session Migration for Claude Code
Move the Session
Without Breaking It
Move a Claude Code session to the project it actually belongs to, subagent transcripts included, so /resume finds it there instead of the old one.
The session you need is filed under the wrong project. Moving it by hand quietly breaks it.
The external problem
A session started under one project’s folder, but the conversation actually belongs under another. /resume in the right project comes up empty, and a plain file move doesn’t fix it: the transcript still points at the old path in nine different encodings.
The internal problem
You can see the .jsonl file sitting right there on disk. But every check Claude Code runs says it belongs to a different project, so it stays invisible exactly when you want it back.
What's at stake
Hours hand-editing paths that half-work, or a naive copy that leaves the subagent transcripts behind, corrupts the cwd field, and leaves you with no backup to recover from.
Five steps: back up, copy, rewrite paths, note it, verify.
Point it at a session UUID and a target project; it handles the backup, the copy, and the verification without you touching a path by hand.
Backup Both Sides
Full copies of the source and target project directories, taken before anything is touched, so there’s a rollback and a ground truth to validate against.
Sidecar-Aware Copy
The session’s .jsonl moves together with its subagents/ sidecar directory, so subagent transcripts don’t get left behind the way a plain copy would leave them.
Rewrite Every Path
All nine path-encoding variants get rewritten across every entry: JSON-escaped and plain backslash, forward slash, MSYS, hyphenated project name, and both drive-letter cases.
Migration Note
A visible message gets appended to the transcript recording what moved and how to recover, so you and Claude both see it on the next /resume.
Verify End-to-End
A validator checks JSONL integrity, path consistency, sidecar files, and the pre-migration backup before anything gets called done, so success is proven, not assumed.
Reference library: Grounded in what actually breaks.
Nine path forms exist because nine different subsystems write paths into a transcript, and the failure modes below all happened for real: a missed sidecar, a false-positive stale-reference warning, an ambiguous UUID lookup after migration. The script and its validator are built against these two files, not a guess at how Claude Code stores sessions.
Supporting reference files follow the practical guide. Archived source material and author workflow notes are not a current policy certification.
01 Path EncodingThe nine forms a Windows path takes inside a transcript, and where each one shows up.
Reference
Path Encoding
The nine variants
For an old path C:\Users\name\old\repo migrating to C:\Users\name\new\repo, the script rewrites all of these:
| Key | Encoding | Example old form | Where it appears |
|---|---|---|---|
| A | JSON-escaped backslash, uppercase drive | C:\\Users\\name\\old\\repo | cwd field on most entries; tool inputs serialized as JSON strings. This is usually the highest-count replacement by far. |
| B | JSON-escaped backslash, lowercase drive | c:\\Users\\name\\old\\repo | Rare; only when something on the system normalized the drive to lowercase. |
| C | Forward slash, uppercase drive | C:/Users/name/old/repo | Tool outputs from Unix-ish utilities running on Windows (e.g. find, grep via Git Bash). |
| D | Hyphenated project-dir name, lowercase drive | c--Users-name-old-repo | References to the encoded project dir under .claude/projects/ in lowercase. |
| E | MSYS / Git Bash path | /c/Users/name/old/repo | Bash tool outputs from MSYS / Git Bash. |
| F | Hyphenated project-dir name, uppercase drive | C--Users-name-old-repo | References to the encoded project dir, the form Claude Code itself uses on Windows. |
| G | Forward slash, lowercase drive | c:/Users/name/old/repo | Rare lowercase-drive variant of C. |
| H | Plain backslash, uppercase drive | C:\Users\name\old\repo | Conversation text — when Claude prints a path inline, it usually uses this form. |
| I | Plain backslash, lowercase drive | c:\Users\name\old\repo | Rare lowercase-drive variant of H. |
How the encoded project-dir name is built
Given a Windows path like C:\Users\name\old\repo:
- Take the drive letter and colon →
C: - Append each path segment separated by
\→C:\Users\name\old\repo - Replace every
:,\,/, space, and'with-→C--Users-name-old-repo
This is the folder name under ~/.claude/projects/. Claude Code creates the uppercase-drive form on Windows; the lowercase form exists for case-insensitive filesystem quirks.
Why this matters for migrations
Most replacements happen in the cwd field (variant A). But other variants show up in:
- Subagent transcripts that captured shell output (variants C, E, G)
- Tool result strings where Claude or a tool quoted a path (variant H)
- References to other sessions or the project dir itself (variants D, F)
The replacement count printed by the migration script's dry-run reveals which subsystems your session interacted with. A session that only ever talked to native Windows tools will show 100% pattern A; one that ran a lot of git or bash will show a mix.
What does NOT get rewritten
- The new project's encoded folder name (
new-repo'sC--...form). This is computed from--new-repoand used as the target directory name; it isn't substituted into entry bodies. - File contents outside the session transcripts. The script operates only on text files inside the project directory under
~/.claude/projects/. - Anything that doesn't include the old path as a substring. The script does literal substring matching, not pattern matching.
What to do when the new path is a substring of the old path (or vice versa)
This happens when you migrate a session into a subdirectory of its current project (e.g. Other Claude Code → Other Claude Code\Sub-Project). The script handles it correctly thanks to longest-first sorting, but its post-migration verifier will produce false-positive warnings because every occurrence of the new path also contains the old path as a substring.
See references/troubleshooting.md → "Stale reference false positive" for the recipe that distinguishes real stale references from prefix-containment artifacts.
02 TroubleshootingFixes for stale-reference false positives, missed sidecars, and ambiguous UUID lookups.
Reference
Troubleshooting
Stale reference false positive
Symptom. The script prints, for the migrated file:
Stale reference in: <new-path>\<uuid>.jsonl (matches: C:\\Users\\...) WARNING: Found N file(s) in the new project dir that still contain old path references.
When this is harmless. When the new project path contains the old project path as a prefix (e.g. you migrated C:\Users\me\Workspace → C:\Users\me\Workspace\Sub-Project), every successfully rewritten occurrence of the new path also contains the old path as a substring. The verifier does naive substring matching, so it flags itself.
Diagnostic — count GENUINELY stale occurrences. Run the bundled validator with --old-repo and --new-repo; the "Stale path references" check uses a negative-lookahead that filters out the prefix-containment false positives. It also scopes the check to entries that existed at migration time, ignoring any later activity that legitimately references the old path:
python <skill-dir>/scripts/validate-migration.py \ "<target-jsonl>" \ --old-repo "<source-real-path>" \ --new-repo "<target-real-path>"
If that check passes, the migration script's own warning was a false positive — move on. If it fails, the failure detail names the specific entries and counts; figure out which encoding variant the migration script missed (see path-encoding.md) and either re-run with a fix or hand-patch the file.
Sidecar / subagent files left behind
Symptom. The migrated session's brief shows subagents: 0, but the original had several. Or --mode subagent-list against the migrated file returns nothing.
Cause. In an older version of the script's single-session mode, only the top-level <uuid>.jsonl was copied — the <uuid>/subagents/ sidecar directory was missed because the filter matched on basename only.
Fix. The current script copies the sidecar tree automatically when --session is set. If you see this symptom, you're running an out-of-date copy of the script. Use the bundled one at scripts/migrate-claude-history.js.
Recovery if it already happened. Just re-run the migration. The script's "skip if destination exists" check means the already-copied .jsonl won't be touched, and the sidecar files will be added on the second pass.
Ambiguous UUID lookup
Symptom. After migration, read-claude-session-history --mode lookup --uuid <prefix> returns:
Ambiguous prefix '<uuid>' matches 2 sessions: <source-project>/<uuid>.jsonl <target-project>/<uuid>.jsonl
Cause. This is expected and correct — the migration is non-destructive. The source copy is still in place as a safety net until the user confirms /resume works under the new project.
Fix. Once the user has confirmed the migrated session resumes correctly under the new project, delete the source copy:
Remove-Item "<source-project-encoded-dir>\<uuid>.jsonl" Remove-Item -Recurse "<source-project-encoded-dir>\<uuid>" # sidecar dir
Never delete before the user confirms. The backup folder is a fallback if the user discovers something broken later, but the in-place source copy is the fastest recovery path.
/resume doesn't show the session under the new project
Symptom. User runs claude in the new project's working directory, types /resume, and the migrated session doesn't appear in the list.
Diagnosis — go through these in order.
- Confirm the migrated `.jsonl` is in the right encoded folder. The folder under
~/.claude/projects/must exactly match the encoded form of the real path the user iscd'd into. Case differences (C--Foovsc--Foo) and missing/added hyphens both break the match. Compare: get the real cwd → encode it (drop drive colon, replace separators with-) → ensure that's the folder name.
- Confirm the `cwd` field inside the entries matches. A surprising amount of
/resumelogic keys off the entries'cwdfield, not the folder name. Run the distinct-cwd check from SKILL.md step 7 — every entry should be the new path (or empty for marker entries).
- Confirm the `.jsonl` is not zero-byte or malformed. Open it:
python -c "import json; [json.loads(l) for l in open(r'<path>', encoding='utf-8') if l.strip()]"— if this errors, the migration corrupted something.
- Check whether Claude Code stripped or reordered entries. Claude Code occasionally writes
permission-modeandai-titlemetadata entries when something opens a file. These are harmless. But if the count is far off from the original (say, more than +5), something else is wrong.
"Cannot find old project directory" error from the script
Symptom. Script exits with: Could not find old Claude project directory. Checked: ...
Cause. The --old-repo value's encoded form doesn't match any folder under ~/.claude/projects/. Most often this is because the user gave a real path that doesn't actually have any sessions yet (the project folder gets created lazily).
Fix. Run ls ~/.claude/projects/ and find the folder name that corresponds to the user's intended source. Reverse-engineer the real path from the folder name and pass that as --old-repo. The encoding is: C--<rest> becomes C:\<rest with hyphens turned back into backslashes>.
The migration note was accidentally appended twice
Symptom. Two <session-migration-note> blocks at the tail of the file.
Cause. Pre-fix versions of the append routine didn't dedupe; or the file was edited between two script runs.
Fix. The current script checks the last few entries for an existing <session-migration-note> and won't append a duplicate. To clean up an already-doubled note, hand-edit the file: remove the older note entry, keep the newer one. Always backup the file first.
Forgetting `--session` and migrating the whole project
Symptom. Script copies hundreds of files, takes much longer than expected, prints replacement counts in the thousands. The target project dir suddenly has many .jsonl files.
Cause. Without --session, the script's default mode migrates every session in the source project — that's how the script was originally written, for the rename-a-project use case.
Fix. Stop the script (Ctrl-C if still running). Delete the unintended files from the target project dir (compare with the target backup to know what wasn't there before). Re-run with --session <uuid> this time.
This is why backing up the target dir matters as much as backing up the source — without it, recovering from this mistake is much harder.
Use it now. It's free.
Works on all platforms. Pick yours and get set up in under a minute.
Claude.ai
Download & upload in 60 seconds
Download the zip, then open Claude.ai to upload it.
Download the zip below. With JavaScript enabled, Claude.ai opens in a new tab if your browser allows it. Otherwise, use Open Claude.ai.
Click the + button in the skills column on the left.
Select Create a skill.
Select Upload a skill and upload the zip.
Start your session migration by running /estack-migrate-claude-session-history.
Claude Code
Run one command in any terminal
Works anywhere Node.js is installed — your project directory, home directory, anywhere.
Open your terminal app and run this command.
npx elliot-stack@latest
Run the command.
Start Claude Code by typing claude in your terminal.
Start your session migration by running /estack-migrate-claude-session-history.
ChatGPT / Other
Paste a prompt — the AI does the rest
This prompt tells the AI where to fetch current instructions from the live site. No installs. No version lag.
Copy the prompt below.
Preview prompt
# Migrate Claude Session History
## When this skill applies
The user wants a specific session (or a handful of sessions) that currently lives under Project A in `~/.claude/projects/` to instead live under Project B, so that `claude --resume` and `/resume` find it under B and the conversation's recorded working directory matches B.
This is **not** the right skill for:
- Listing / searching / reading sessions → use `read-claude-session-history`
- Recovering deleted sessions from backups → use the `.claude-backups` snapshots via `read-claude-session-history`
- Renaming a project's working directory and moving **all** of its sessions at once → use `https://elliotdrel.com/e-stack/migrate-claude-session-history/scripts/migrate-claude-history.js` directly without the `--session` flag (it has a full-project mode)
- A brand-new conversation in a different folder → just start a fresh Claude Code session there
## Why this is not a one-liner
A Claude Code session is keyed by the project's working directory, which gets encoded into the project folder name under `~/.claude/projects/`. The session's `.jsonl` transcript contains hundreds of references to that directory across **nine** path-encoding variants (JSON-escaped backslash, plain backslash, forward slash, MSYS, hyphenated project-dir name — each in upper/lower drive-letter forms). A `cwd` field exists on most entries. There is also a sidecar directory (`<uuid>/subagents/`) holding subagent transcripts that must move together.
Just `mv` will not work. The bundled script handles all of this; the workflow below ties it together with a backup, a visible migration note, and verification.
See `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/path-encoding.md` for the encoding reference.
## Workflow
Work through these steps in order. Skipping the plan / backup / verification steps is exactly how a migration goes wrong silently — the script reports success, but `/resume` fails to find the session or loads it under the wrong project.
### 1. Resolve the inputs
You need three things. Treat the conversation as the primary source — only ask the user for what is genuinely missing.
| Input | How to resolve |
|---|---|
| **Session UUID** | If the user gave a UUID, use it. If they gave a session file path, take the basename without `.jsonl`. If they only described the session ("the one where we did X"), use `read-claude-session-history --mode search --all-projects --query "<keywords>"` to find candidates and confirm with the user. |
| **Source project path** (the real cwd) | Run `python <read-claude-session-history>/scripts/read_transcript.py --mode lookup --uuid <prefix>` to get the source `.jsonl` path. Reverse the encoded folder name back into a real Windows path: drop the leading `C--` (becomes `C:\`) and convert each `-` between path segments back to `\`. Confirm by reading the `cwd` field of any entry in the file. |
| **Target project path** (where the session should live) | Ask the user, unless the conversation already named it (e.g. "move it to `~\Foo\Bar`"). The target project directory under `~/.claude/projects/` does **not** need to exist yet — the script creates it. The encoded folder name is derived from the path. |
If the source and target encoded folder names are identical, the migration is a no-op — tell the user.
### 2. Present the plan and confirm
Before touching anything, show the user a short plan with:
- Source `.jsonl` path
- Target `.jsonl` path
- Old cwd → New cwd (the values that will be rewritten)
- Backup location (default: `<source-real-path>\session-backups\<timestamp>-pre-migration\`, or a path the user prefers)
- A note that the script will also append a visible user-message migration note to the migrated transcript (on by default; see step 6)
Wait for explicit "go ahead." Migrations touch files Claude Code reads on every `/resume`; a wrong target is annoying to recover from. The backup is the safety net, but confirming first means we usually don't need to use it.
### 3. Back up both project directories — full copies, both sides
Robocopy is the right tool on Windows — fast and resilient with large dirs:
```powershell
$ts = Get-Date -Format "yyyy-MM-dd-HHmmss"
$backupRoot = "<chosen-backup-root>\$ts-pre-migration"
New-Item -ItemType Directory -Force -Path $backupRoot | Out-Null
robocopy "<source-project-dir>" "$backupRoot\<source-folder-name>" /E /NFL /NDL /NJH /NJS /NP /MT:8 | Out-Null
robocopy "<target-project-dir>" "$backupRoot\<target-folder-name>" /E /NFL /NDL /NJH /NJS /NP /MT:8 | Out-Null
```
Back up the **entire** source project dir **and** the **entire** target project dir, even if the target only has one or two unrelated sessions. These backups serve two purposes, and the second one is the one people forget:
1. **Rollback safety net.** If anything in the migration goes wrong, you can restore both sides to their pre-migration state in one command.
2. **Ground truth for validation.** The backup of the source dir is the only authoritative record of what the original transcript looked like — every entry, every path string, every sidecar file. After migration, step 7 will diff the migrated content against the backup to prove that **every** old-path occurrence was rewritten (no encoding variant was missed) and **no** entries were lost, duplicated, or reordered. The backup of the target dir proves you only **added** files to it — you didn't accidentally overwrite anything that was already there. Without both backups, "the migration worked" is hope, not verification.
Robocopy's exit codes are non-standard — exit 1 means "files copied successfully," not an error. After it finishes, report the file counts and sizes from `Get-ChildItem ... -Recurse | Measure-Object` so the user sees the backup actually contains something.
### 4. Dry-run, then execute
```bash
node <skill-dir>/scripts/migrate-claude-history.js \
--old-repo "<source-project-real-path>" \
--new-repo "<target-project-real-path>" \
--session <session-uuid> \
--dry-run
```
The dry-run prints:
- Which `.jsonl` plus how many sidecar files would be copied
- Replacement counts per path-encoding variant (most sessions hit only pattern A — JSON-escaped backslash, upper-drive — because that's what `cwd` fields use)
If the dry-run output looks wrong (zero sidecar files when there should be subagents, wildly different replacement counts than expected, or zero replacements at all), stop and investigate before running for real. See `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/troubleshooting.md`.
Then run without `--dry-run` to execute. The script:
- Copies the `<uuid>.jsonl` to the target project dir, applying all 9 path replacements
- Copies the entire `<uuid>/subagents/` sidecar tree (subagent transcripts + meta files) with the same replacements
- Appends a visible migration note as a regular user message to the main `.jsonl` (see step 6)
- Runs its own stale-reference verifier and reports any matches
### 5. Handle the "stale reference" warning
When the **new** project path contains the **old** project path as a prefix (e.g. moving from `Other Claude Code` → `Other Claude Code\Personal-Health-Project`), the script's verifier will warn about "stale references" in the migrated file. These are **false positives**: every occurrence of the old path is now actually inside a new-path string (since the new path begins with the old path).
Confirm it really is a false positive by counting genuine stale references — occurrences of the old path that are **not** followed by the new path's added segment. A Python check is in `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/troubleshooting.md`. If true-stale count is zero, ignore the warning.
If true-stale count is non-zero, **do not** declare success. Investigate which pattern the script missed and either fix the script or hand-patch the file.
### 6. The migration note
By default, the script appends a `type: "user"` entry (no `isMeta`) as the last entry of the migrated `.jsonl`. This entry:
- Tells future-Claude (and the user, when scrolling the conversation) that the session was migrated, what was rewritten, and how to recover when a rewritten path no longer exists on disk
- Is intentionally **not** `isMeta: true` — the user wants both themselves and the AI to see it on `/resume`
- Is duplicate-safe — the script's append routine checks the last few entries for an existing `<session-migration-note>` block and refuses to add a second
Users can opt out with `--no-migration-note`, but the script prints a warning that this is strongly discouraged. Do not pass `--no-migration-note` unless the user has explicitly asked for it.
### 7. Verify end-to-end — and validate against the backup
Run the bundled validation script. It consolidates every structural, schema, path-consistency, sidecar, and (optional) backup-cross-validation check into one invocation, prints a per-check PASS/FAIL table, and exits non-zero on any failure.
```bash
python <skill-dir>/scripts/validate-migration.py \
"<target-project-encoded-dir>/<uuid>.jsonl" \
--old-repo "<source-real-path>" \
--new-repo "<target-real-path>" \
--source-backup "<backup-root>/<source-folder-name>/<uuid>.jsonl" \
--target-backup-dir "<backup-root>/<target-folder-name>"
```
The script runs these checks in order — most of them require no flags, the path checks need `--old-repo` and `--new-repo`, and the cross-validation checks need `--source-backup` (with `--target-backup-dir` enabling the "target untouched" sub-check):
| Check | What it validates | Needs flags |
|---|---|---|
| JSONL parse integrity | Every line is valid JSON | — |
| Schema consistency | Each entry has `type`; user/assistant entries have well-formed `message`; uuids and parentUuids are UUID-shaped | — |
| Session ID consistency | Every entry's `sessionId` matches the file's UUID | — |
| Parent UUID chains | Every non-null `parentUuid` resolves to a uuid present in the file | — |
| CWD field consistency | All non-empty `cwd` values are identical (and equal `--new-repo` if passed) | optionally `--new-repo` |
| Migration note present | Exactly one `<session-migration-note>` entry exists, is `type: "user"`, no `isMeta` | — |
| Stale path references | No "truly-stale" old-path references in entries that existed at migration time (post-note entries are skipped — those are later activity that can legitimately reference the old path) | `--old-repo` + `--new-repo` |
| Sidecar integrity | Every subagent `.jsonl` in `<uuid>/` parses and shares the parent `sessionId` | — |
| Backup cross-validation | Source backup parses; entry count = source + 1; every source uuid present in order; sidecar count matches; pre-existing target files unchanged | `--source-backup` (+ `--target-backup-dir`) |
If anything fails, stop. Read the failed check's detail line — it points at the specific entry index or file. The backup is right there; if recovery is needed: `robocopy <backup-dir> <live-dir> /MIR`.
All checks must pass before declaring success. The script's final line is the summary you report back to the user.
### 8. Tell the user what's next, and tear down the safety net
After verification, the user still has work to do. Walk them through these in order — each one unlocks the next.
1. **Test `/resume` in the new project's working directory.** This is the real validation. The migrated session should appear in the resume picker and load with the full conversation history. If it doesn't, **stop** — do not delete anything. See `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/troubleshooting.md` → "/resume doesn't show the session under the new project" for diagnosis.
Give the user a ready-to-run command they can copy directly. Format it in a fenced code block:
```
cd "<target-project-real-path>";claude -r <session-uuid>
```
Example: `cd "C:\Users\2supe\Other Claude Code\Personal-Health-Project";claude -r ef382169-d56b-4850-b092-8084a52983ef`
2. **Once `/resume` works, delete the original session from the source project.** Until they do, `--mode lookup` will report the UUID as ambiguous, and Claude Code may still find the session under the old project. Ask the user before running these yourself — deletion is irreversible:
```powershell
Remove-Item "<source-project-encoded-dir>\<uuid>.jsonl"
Remove-Item -Recurse "<source-project-encoded-dir>\<uuid>" # sidecar dir
```
### 9. Clean up the backups — the final step
Once both of the above are done, **the migration is locked in** and the pre-migration backup folder created in step 3 is just bloat. Robocopy backups of `.claude/projects/` directories run hundreds of megabytes; do not let them accumulate. Delete the entire backup folder created for this migration:
```powershell
Remove-Item -Recurse -Force "<backup-root>"
```
Confirm with the user before deleting and report the freed size. Do **not** skip this step or default to "keep it for a few days" — if `/resume` worked and the source copy is gone, the backup has done its job. Keeping it costs disk and clutters the workspace.
The only reason to keep a backup is if you have not yet verified `/resume` works **or** you have not yet deleted the source copy. In either of those cases, you are still in steps 1-2, not step 9.
## Common pitfalls
These are the failure modes that have actually happened — read `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/troubleshooting.md` for the fixes.
- Forgetting the sidecar dir — the main `.jsonl` migrates but the subagent transcripts get left behind, so the migrated brief shows `subagents: 0` even though the original had many. The script's `--session` mode now handles this automatically, but verify with the subagent-list check.
- Treating "stale reference" warnings as real when the new path is a subdir of the old path.
- Running the migration without `--session`, which migrates **every** session in the source project (the constants/CLI default is full-project mode).
- Source-path encoding mismatch — Claude Code creates `C--Foo` on Windows but case-insensitive filesystems can produce `c--Foo`. The script tries both.
- Forgetting to rewrite `gitBranch` / `version` consistency on the appended note — the script copies these from the last uuid-bearing entry; do not invent values.
## Files in this skill
- `https://elliotdrel.com/e-stack/migrate-claude-session-history/scripts/migrate-claude-history.js` — the migration script. Supports full-project and single-session modes, CLI overrides for old/new repo, auto-append of the migration note (on by default), `--no-migration-note` opt-out, and `--dry-run`. Run `node https://elliotdrel.com/e-stack/migrate-claude-session-history/scripts/migrate-claude-history.js --help` for the full CLI.
- `https://elliotdrel.com/e-stack/migrate-claude-session-history/scripts/validate-migration.py` — post-migration validator. Runs structural, schema, path-consistency, sidecar, and (optional) backup-cross-validation checks on a migrated `.jsonl`. Exits 0 if every check passes, 1 otherwise. Run `python https://elliotdrel.com/e-stack/migrate-claude-session-history/scripts/validate-migration.py --help` for the full CLI. Use this in step 7 instead of writing ad-hoc Python.
- `tests/estack-migrate-claude-session-history/test-append-note.js` — smoke test for the note-append routine (path relative to repo root). Run with `node tests/estack-migrate-claude-session-history/test-append-note.js` from the repo root. Useful if you edit the migration script and want to sanity-check the duplicate-detection and non-meta entry shape.
- `tests/estack-migrate-claude-session-history/test-validate-migration.py` — self-test for the validator (path relative to repo root). Runs 27 synthetic cases covering every check. Run with `python tests/estack-migrate-claude-session-history/test-validate-migration.py` from the repo root. Exit 0 on full pass, 1 if any case fails.
- `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/path-encoding.md` — the 9 path-encoding variants, why each exists, which entries use which form.
- `https://elliotdrel.com/e-stack/migrate-claude-session-history/references/troubleshooting.md` — recoveries for stale-reference false positives, missed sidecars, ambiguous lookups, and the true-stale grep recipe.
---
## Skill Feedback
If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
```bash
gh issue create \
--repo ElliotDrel/e-stack \
--title "estack-migrate-claude-session-history: <concise summary>" \
--body "<description from user feedback — expected vs. actual behavior and context>"
```
**If `gh` is not installed**, build a pre-filled URL:
```bash
python3 -c "
import urllib.parse
title = 'estack-migrate-claude-session-history: <concise summary>'
body = '<description from user feedback — expected vs. actual behavior and context>'
base = 'https://github.com/ElliotDrel/e-stack/issues/new'
print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
"
```
Share the printed URL with the user and offer to open it in their browser.
They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.
Open your platform and paste the prompt.
Start your session migration.
Migrate Claude Session History ships in E-Stack, a set of 21 free skills installed by one command. See the whole stack.