conversation-sync

name	conversation-sync
description	Sync conversation history from .codex/sessions to .claude.json for context preservation. Use when copying/syncing conversations, importing sessions, or backing up conversation context.
version	1.0.1
tags	["conversations","sync","backup","context"]
status	production
triggers	["copy conversations","sync conversations","import sessions","conversation backup"]
author	Claude Code

Conversation Sync Skill

Note: This skill references .codex/sessions which may be outdated. Verify session storage paths match your Claude Code version before use.

This skill copies Claude Code conversation session files from .codex/sessions to the repository's .claude.json file for context preservation and backup.

Purpose

When working across different environments (e.g., after WSL/Docker crashes), conversation history stored in .codex/sessions can be referenced in .claude.json to maintain context continuity.

Usage

# Sync conversations from last N days (default: 7)
./.claude/skills/conversation-sync/sync-conversations.sh --days 7

# Sync conversations from a specific project
./.claude/skills/conversation-sync/sync-conversations.sh --project claude-flow-novice

# Sync conversations from a specific date range
./.claude/skills/conversation-sync/sync-conversations.sh --from 2025-11-20 --to 2025-11-26

# Dry run (show what would be copied)
./.claude/skills/conversation-sync/sync-conversations.sh --dry-run

What It Does

1. Searches .codex/sessions for conversation JSONL files
2. Filters by project working directory (if specified)
3. Filters by date range
4. Creates/updates .claude.json with references to conversation files
5. Preserves existing conversations in .claude.json

Output Format

The skill updates .claude.json with this structure:

{
  "conversations": [
    {
      "session_id": "rollout-2025-11-24T10-24-43-019ab71c-699f-7052-8ce1-892b6208ba94",
      "date": "2025/11/24",
      "file": "/mnt/c/Users/masha/.codex/sessions/2025/11/24/rollout-2025-11-24T10-24-43-019ab71c-699f-7052-8ce1-892b6208ba94.jsonl"
    }
  ]
}

Notes

• Conversation files remain in their original locations
• Only references are added to .claude.json
• Supports both Windows (/mnt/c/Users/...) and Linux paths with automatic normalization
• Safe to run multiple times (idempotent)
• Path normalization handles both backslashes (\) and forward slashes (/)
• Case-insensitive matching for project filtering (works with mixed-case paths)

Location of Conversation Data

• Primary: /mnt/c/Users/{username}/.codex/sessions/YYYY/MM/DD/*.jsonl
• Alternate: ~/.codex/sessions/YYYY/MM/DD/*.jsonl
• Docker mounts: /mnt/wsl/docker-desktop-bind-mounts/ (if applicable)

Requirements

• jq - JSON processing
• bash 4.0+
• Access to .codex/sessions directory