session-import

Instructions

Import a JSONL session file so it appears in this project's Claude Code session history.

Step 1 — Validate the file

Get the filename from the user's argument or ask for it.

IMPORT_FILE="<filename from user>"

# Check file exists
if [ ! -f "$IMPORT_FILE" ]; then
  echo "ERROR: File not found: $IMPORT_FILE"
  exit 1
fi

# Preview first few lines to confirm it's a valid session
head -3 "$IMPORT_FILE"
wc -l "$IMPORT_FILE"

If the file doesn't look like a Claude Code session JSONL (should contain queue-operation or sessionId), warn the user and confirm before proceeding.

Step 2 — Find sessions directory

ENCODED=$(echo "$PWD" | sed 's|/|-|g; s| |-|g; s|~|-|g')
SESSION_DIR=~/.claude/projects/"$ENCODED"
mkdir -p "$SESSION_DIR"
echo "Target sessions dir: $SESSION_DIR"

Step 3 — Extract or generate session ID

# Try to extract sessionId from the JSONL
SESSION_ID=$(python3 -c "
import sys, json
for line in open('$IMPORT_FILE'):
    try:
        obj = json.loads(line)
        sid = obj.get('sessionId') or obj.get('session_id')
        if sid:
            print(sid)
            break
    except: pass
" 2>/dev/null)

# Fallback: use the filename stem if it looks like a UUID
if [ -z "$SESSION_ID" ]; then
  STEM=$(basename "$IMPORT_FILE" .jsonl)
  if echo "$STEM" | grep -qE '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'; then
    SESSION_ID="$STEM"
  fi
fi

# Last resort: generate a new UUID
if [ -z "$SESSION_ID" ]; then
  SESSION_ID=$(uuidgen 2>/dev/null | tr '[:upper:]' '[:lower:]' || python3 -c "import uuid; print(uuid.uuid4())")
fi

echo "Session ID: $SESSION_ID"
DEST="$SESSION_DIR/$SESSION_ID.jsonl"
echo "Destination: $DEST"

Step 4 — Warn if session already exists

if [ -f "$DEST" ]; then
  echo "WARNING: A session with ID $SESSION_ID already exists at $DEST"
  echo "Overwrite? (If yes, continue; if no, stop here)"
fi

Ask the user if they want to overwrite, unless it's clearly safe (e.g., file sizes differ significantly).

Step 5 — Copy to sessions directory

cp "$IMPORT_FILE" "$DEST"
ls -lh "$DEST"
echo "Import complete."

Step 6 — Confirm and guide the user

Tell the user:

• Session ID that was imported
• Full path of the destination file
• How to access it: In Claude Code, use the session picker (the history list) — the imported session should appear with its original timestamp. You may need to restart Claude Code or open a new window for it to appear.
• If the imported session was from a different project path, the conversation context will still be readable but code references may not map to local files.