Claude Code Skill

session-merge

Merge split or related Claude Code sessions into a single continuous conversation history.

# The Problem

Claude Code sessions split unexpectedly. You're deep in a session, you cd to a different directory, or you /exit and --resume, and suddenly your single conversation has been fragmented into two separate sessions. The older one has all your context and history; the newer one has your latest work. There's no built-in way to put them back together.

This happens because Claude Code scopes sessions to working directories. Change your cwd and it may silently create a new session, inheriting the name but not the history. Over time, you accumulate duplicate-named sessions that were supposed to be one continuous conversation.

# The Solution

session-merge is a Claude Code skill that detects split sessions and merges them back together. It works directly with the JSONL session files in ~/.claude/projects/, stitching conversation trees together and producing a single unified session you can resume from your home directory.

# Quick Start

Find all your split sessions (sessions sharing the same name):

# Detect all split session groups
bash ~/.claude/skills/session-merge/scripts/merge_sessions.sh --find-splits

Auto-fix all of them at once:

# Merge every split group back into one session
bash ~/.claude/skills/session-merge/scripts/merge_sessions.sh --merge-splits

Or merge specific sessions manually:

# Dry run first
bash merge_sessions.sh --dry-run --name "my-session" <id1> <id2>

# Execute the merge
bash merge_sessions.sh --name "my-session" <id1> <id2>

# Resume the merged session (always from ~)
cd ~ && claude --resume <merged-session-uuid>

# How It Works

Collects all JSONL entries from each source session

Finds the main trunk of each session — the longest parentUuid chain from leaf to root

Stitches trunks together by linking the root of session N+1 to the leaf of session N, creating one continuous conversation chain

Writes all entries to the home directory project (~/.claude/projects/) with updated session IDs and index metadata

Tree stitching ensures Claude Code can walk one continuous parentUuid chain when resuming, rather than seeing disconnected fragments. All merged sessions live in your home directory project so they're always resumable from ~.

# All Flags

--list            List all sessions across all projects
--list-project <p> List sessions for a specific project
--find-splits     Detect duplicate-named session groups
--merge-splits    Auto-merge all split groups (with confirm)
--name <name>     Name for the merged session
--delete-sources  Remove originals after merge
--dry-run         Preview without making changes
--output-id <id>  Specify a UUID for the merged session

# Install

Copy the skill into your Claude Code skills directory:

# Clone the repo
git clone https://github.com/qsimeon/session-merge.git

# Copy to your Claude skills directory
cp -r session-merge ~/.claude/skills/session-merge

# Or symlink it
ln -s $(pwd)/session-merge ~/.claude/skills/session-merge

Then invoke it from any Claude Code session with /session-merge.

# File Structure

session-merge/ ├── SKILL.md # Skill definition (Claude reads this) └── scripts/ └── merge_sessions.sh # The merge engine (~800 lines)

# Why Sessions Split

Claude Code sessions are scoped to working directories. The most common causes of unexpected splits:

Directory changes

Running cd to a different project path can trigger a new session scoped to the new directory.

Exit/resume cycles

claude --resume sometimes reconnects to the wrong session when multiple share the same name.

Version updates

Upgrading Claude Code between sessions can occasionally break session continuity.