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/, combining entries chronologically and producing a single unified session you can resume normally.

# 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
claude --resume "my-session"

# How It Works

Collects all JSONL entries from each source session

Sorts entries chronologically by timestamp, interleaving conversations in the order they actually happened

Rewrites the sessionId field on every entry to the new merged UUID, so Claude Code treats them as one session

Copies subagent files and updates the session index metadata

Message threading (parentUuid) within each original session is preserved. Only the session-level identity changes.

# 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.