claude-session-share 1.0.0

package/dist/services/session-importer.js

@@ -0,0 +1,88 @@
+/**
+ * Session import service
+ *
+ * Orchestrates the complete workflow of importing a Claude Code session from GitHub Gist:
+ * 1. Fetch gist content
+ * 2. Extract session JSONL
+ * 3. Parse messages with error recovery
+ * 4. Remap UUIDs to avoid conflicts
+ * 5. Write to local storage
+ */
+import { GistClient } from '../gist/client.js';
+import { UUIDMapper } from '../utils/uuid-mapper.js';
+import { writeSessionToLocal } from '../session/writer.js';
+/**
+ * Import a session from GitHub Gist
+ *
+ * Fetches a shared session gist, remaps UUIDs, and writes to local storage.
+ * Includes error recovery for malformed messages (logs and continues).
+ *
+ * @param gistIdOrUrl - GitHub Gist URL or bare gist ID
+ * @param projectPath - Local project directory path (e.g., "/Users/name/project")
+ * @returns Promise resolving to import result with session path and metadata
+ * @throws Error if gist not found, no JSONL file, or write fails
+ *
+ * @example
+ * const result = await importSession('https://gist.github.com/user/abc123', '/Users/name/project');
+ * console.log(`Imported ${result.messageCount} messages to ${result.sessionPath}`);
+ */
+export async function importSession(gistIdOrUrl, projectPath) {
+    try {
+        // Step 1: Initialize GistClient (validates GITHUB_TOKEN)
+        const gistClient = new GistClient();
+        // Step 2: Fetch gist content
+        const gist = await gistClient.fetchGist(gistIdOrUrl);
+        // Step 3: Extract session JSONL file
+        // Look for file with .jsonl extension
+        const jsonlFileName = Object.keys(gist.files).find((name) => name.endsWith('.jsonl'));
+        if (!jsonlFileName) {
+            throw new Error('No JSONL file found in gist. Expected a .jsonl file containing session messages.');
+        }
+        const jsonlFile = gist.files[jsonlFileName];
+        if (!jsonlFile || !jsonlFile.content) {
+            throw new Error(`JSONL file "${jsonlFileName}" has no content. The gist may be malformed.`);
+        }
+        const jsonlContent = jsonlFile.content;
+        // Step 4: Parse messages with per-line error recovery
+        const messages = [];
+        const lines = jsonlContent.split('\n').filter((line) => line.trim());
+        let parseErrors = 0;
+        for (const [index, line] of lines.entries()) {
+            try {
+                const message = JSON.parse(line);
+                messages.push(message);
+            }
+            catch (error) {
+                // Log error but continue parsing remaining lines
+                parseErrors++;
+                console.warn(`Failed to parse message at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (messages.length === 0) {
+            throw new Error(`No valid messages found in JSONL file. Parse errors: ${parseErrors}`);
+        }
+        // Log parse errors if any occurred
+        if (parseErrors > 0) {
+            console.warn(`Imported ${messages.length} messages with ${parseErrors} parse errors`);
+        }
+        // Step 5: Remap UUIDs to avoid conflicts
+        const mapper = new UUIDMapper();
+        const remappedMessages = messages.map((msg) => mapper.remapMessage(msg));
+        // Step 6: Write to local storage
+        const result = await writeSessionToLocal(remappedMessages, projectPath);
+        // Step 7: Return import result
+        return {
+            sessionPath: result.filePath,
+            sessionId: result.sessionId,
+            messageCount: remappedMessages.length,
+            projectPath,
+        };
+    }
+    catch (error) {
+        // Add context to errors for better debugging
+        if (error instanceof Error) {
+            throw new Error(`Failed to import session: ${error.message}`);
+        }
+        throw new Error(`Failed to import session: ${String(error)}`);
+    }
+}

package/dist/services/session-uploader.js

@@ -0,0 +1,64 @@
+/**
+ * Session-to-Gist upload service
+ *
+ * Orchestrates the complete workflow of uploading a Claude Code session to GitHub Gist:
+ * 1. Read session messages
+ * 2. Sanitize for privacy
+ * 3. Convert to JSONL format
+ * 4. Extract metadata
+ * 5. Upload to Gist
+ */
+import { parseSessionFile } from '../session/reader.js';
+import { extractMetadata } from '../session/metadata.js';
+import { sanitizeSession, inferBasePath } from '../sanitization/pipeline.js';
+import { GistClient } from '../gist/client.js';
+/**
+ * Upload a session file to GitHub Gist
+ *
+ * Performs full sanitization pipeline and uploads to secret (unlisted) Gist.
+ *
+ * @param sessionPath - Absolute path to session JSONL file
+ * @returns Promise resolving to Gist URL
+ * @throws Error if any step fails (reading, sanitizing, uploading)
+ *
+ * @example
+ * const url = await uploadSession('/Users/name/.claude/projects/abc/session.jsonl');
+ * console.log(`Shared at: ${url}`);
+ */
+export async function uploadSession(sessionPath) {
+    try {
+        // Step 1: Read session messages
+        const messages = await parseSessionFile(sessionPath);
+        if (messages.length === 0) {
+            throw new Error('Session file is empty or contains no valid messages');
+        }
+        // Step 2: Sanitize session for privacy
+        const basePath = inferBasePath(messages);
+        const sanitizedMessages = sanitizeSession(messages, basePath);
+        // Step 3: Convert sanitized messages to JSONL string
+        const sessionJsonl = sanitizedMessages.map(msg => JSON.stringify(msg)).join('\n');
+        // Step 4: Extract metadata for gist description and metadata file
+        const metadata = extractMetadata(sanitizedMessages);
+        if (!metadata) {
+            throw new Error('Failed to extract session metadata');
+        }
+        // Step 5: Upload to Gist
+        const gistClient = new GistClient();
+        // Use metadata title if available, fallback to timestamp-based title
+        const description = metadata.projectPath && metadata.projectPath !== 'unknown'
+            ? `Claude Code Session - ${metadata.projectPath.split('/').pop()}`
+            : `Claude Code Session - ${new Date(metadata.firstTimestamp).toISOString()}`;
+        const response = await gistClient.createGist(description, {
+            'session.jsonl': sessionJsonl,
+            'metadata.json': JSON.stringify(metadata, null, 2),
+        });
+        return response.html_url;
+    }
+    catch (error) {
+        // Add context to errors for better debugging
+        if (error instanceof Error) {
+            throw new Error(`Failed to upload session: ${error.message}`);
+        }
+        throw new Error(`Failed to upload session: ${String(error)}`);
+    }
+}

package/dist/session/finder.js

@@ -0,0 +1,65 @@
+/**
+ * Session file discovery for Claude Code projects
+ *
+ * Finds all session JSONL files (main and agent) for a given project path.
+ * Uses Claude Code's path encoding scheme to locate session directories.
+ */
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+import { getSessionDirectory } from '../utils/path-encoding.js';
+/**
+ * Finds all session files for a project
+ *
+ * Discovers both main session files (uuid.jsonl) and agent session files
+ * (agent-uuid.jsonl) in the project's session directory.
+ *
+ * @param projectPath - Absolute path to the project
+ * @returns Array of session files with metadata
+ * @throws Error if home directory cannot be determined
+ *
+ * @example
+ * const sessions = await findSessionFiles('/Users/name/project');
+ * // Returns: [
+ * //   { path: '/Users/name/.claude/projects/Users-name-project/abc-123.jsonl',
+ * //     sessionId: 'abc-123', isAgent: false },
+ * //   { path: '/Users/name/.claude/projects/Users-name-project/agent-def-456.jsonl',
+ * //     sessionId: 'def-456', isAgent: true }
+ * // ]
+ */
+export async function findSessionFiles(projectPath) {
+    // Get home directory
+    const homeDir = process.env.HOME || process.env.USERPROFILE;
+    if (!homeDir) {
+        throw new Error('Cannot determine home directory: HOME and USERPROFILE environment variables not set');
+    }
+    // Get the encoded session directory path
+    const sessionDir = getSessionDirectory(projectPath);
+    try {
+        // List all files in the session directory
+        const files = await readdir(sessionDir);
+        // Filter and map to SessionFile objects
+        return files
+            .filter(filename => filename.endsWith('.jsonl'))
+            .map(filename => {
+            // Detect agent sessions by filename prefix
+            const isAgent = filename.startsWith('agent-');
+            // Extract session ID: remove 'agent-' prefix if present, then remove '.jsonl' extension
+            const sessionId = isAgent
+                ? filename.replace('agent-', '').replace('.jsonl', '')
+                : filename.replace('.jsonl', '');
+            return {
+                path: join(sessionDir, filename),
+                sessionId,
+                isAgent,
+            };
+        });
+    }
+    catch (error) {
+        // Handle missing directory gracefully - not an error if project has no sessions yet
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        // Re-throw other errors (permission denied, etc.)
+        throw error;
+    }
+}

package/dist/session/metadata.js

@@ -0,0 +1,55 @@
+/**
+ * Session metadata extraction from parsed messages
+ *
+ * Extracts useful metadata from session messages including message counts,
+ * timestamps, project path, and agent conversation detection.
+ */
+/**
+ * Extracts metadata from session messages
+ *
+ * Analyzes message array to extract session metadata including:
+ * - Session ID and project path (from user messages)
+ * - Message count and timestamp range
+ * - Agent conversation detection
+ * - Claude Code version
+ *
+ * @param messages - Array of parsed session messages
+ * @returns Session metadata, or null if messages array is empty
+ *
+ * @example
+ * const messages = await parseSessionFile('/path/to/session.jsonl');
+ * const metadata = extractMetadata(messages);
+ * // Returns: {
+ * //   sessionId: 'abc-123',
+ * //   projectPath: '/Users/name/project',
+ * //   messageCount: 42,
+ * //   firstTimestamp: '2026-01-11T10:00:00.000Z',
+ * //   lastTimestamp: '2026-01-11T11:30:00.000Z',
+ * //   hasAgentConversations: true,
+ * //   version: '1.2.3'
+ * // }
+ */
+export function extractMetadata(messages) {
+    // Return null for empty arrays
+    if (messages.length === 0) {
+        return null;
+    }
+    // Get first and last messages for timestamps
+    const firstMessage = messages[0];
+    const lastMessage = messages[messages.length - 1];
+    // Find first user message to extract cwd and version
+    // Use type guard to safely access UserMessage fields
+    const firstUserMessage = messages.find(m => m.type === 'user');
+    // Detect agent conversations by checking isSidechain flag
+    const hasAgentConversations = messages.some(m => m.isSidechain === true);
+    // Build metadata object with all fields
+    return {
+        sessionId: firstMessage.sessionId,
+        projectPath: firstUserMessage?.cwd || 'unknown',
+        messageCount: messages.length,
+        firstTimestamp: firstMessage.timestamp,
+        lastTimestamp: lastMessage.timestamp,
+        hasAgentConversations,
+        version: firstUserMessage?.version || 'unknown',
+    };
+}

package/dist/session/reader.js

@@ -0,0 +1,101 @@
+/**
+ * Streaming JSONL reader for Claude Code session files
+ *
+ * Provides memory-efficient line-by-line reading with error recovery.
+ * Handles large session files without loading entire content into memory.
+ */
+import { createReadStream } from 'fs';
+import { createInterface } from 'readline';
+/**
+ * Reads session file line-by-line using async generator
+ *
+ * Streams the file efficiently, yielding non-empty lines.
+ * Handles CRLF line endings automatically.
+ *
+ * @param filePath - Absolute path to session JSONL file
+ * @yields Non-empty lines from the file
+ *
+ * @example
+ * for await (const line of readSessionLines('/path/to/session.jsonl')) {
+ *   console.log(line);
+ * }
+ */
+export async function* readSessionLines(filePath) {
+    // Create read stream with UTF-8 encoding
+    const fileStream = createReadStream(filePath, { encoding: 'utf-8' });
+    // Create readline interface for line-by-line reading
+    // crlfDelay: Infinity handles both \n and \r\n line endings
+    const rl = createInterface({
+        input: fileStream,
+        crlfDelay: Infinity,
+    });
+    // Yield each non-empty line
+    for await (const line of rl) {
+        const trimmedLine = line.trim();
+        if (trimmedLine) {
+            yield trimmedLine;
+        }
+    }
+}
+/**
+ * Checks if a parsed object has required session message fields
+ *
+ * @param obj - Parsed JSON object
+ * @returns true if object has required fields (type, uuid, sessionId)
+ */
+function hasRequiredFields(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        'type' in obj &&
+        'uuid' in obj &&
+        'sessionId' in obj &&
+        typeof obj.type === 'string' &&
+        typeof obj.uuid === 'string' &&
+        typeof obj.sessionId === 'string');
+}
+/**
+ * Parses a session JSONL file with error recovery
+ *
+ * Reads the file line-by-line, parsing each line as JSON.
+ * Continues processing even if individual lines fail to parse.
+ * Skips lines missing required fields (type, uuid, sessionId).
+ *
+ * @param filePath - Absolute path to session JSONL file
+ * @returns Array of successfully parsed session messages
+ *
+ * @example
+ * const messages = await parseSessionFile('/path/to/session.jsonl');
+ * console.log(`Loaded ${messages.length} messages`);
+ */
+export async function parseSessionFile(filePath) {
+    const messages = [];
+    let lineNumber = 0;
+    try {
+        // Process each line from the file
+        for await (const line of readSessionLines(filePath)) {
+            lineNumber++;
+            try {
+                // Parse JSON - this is wrapped per line for error recovery
+                const parsed = JSON.parse(line);
+                // Validate required fields exist
+                if (!hasRequiredFields(parsed)) {
+                    console.warn(`[reader] Line ${lineNumber}: Skipping message missing required fields (type, uuid, sessionId)`);
+                    continue;
+                }
+                // Type assertion is safe after validation
+                messages.push(parsed);
+            }
+            catch (parseError) {
+                // Log warning but continue processing remaining lines
+                console.warn(`[reader] Line ${lineNumber}: Failed to parse JSON - ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+                continue;
+            }
+        }
+    }
+    catch (fileError) {
+        // This catches file-level errors (file not found, permission denied, etc.)
+        console.error(`[reader] Error reading file ${filePath}: ${fileError instanceof Error ? fileError.message : String(fileError)}`);
+        throw fileError;
+    }
+    return messages;
+}

package/dist/session/types.js

@@ -0,0 +1,11 @@
+/**
+ * TypeScript types for Claude Code session messages
+ *
+ * Sessions are stored as JSONL files with three message types:
+ * - user: User input messages
+ * - assistant: Assistant responses with thinking snapshots
+ * - file-history-snapshot: File state tracking
+ *
+ * Uses discriminated unions for type-safe message handling.
+ */
+export {};

package/dist/session/writer.js

@@ -0,0 +1,74 @@
+/**
+ * Session writer for local JSONL storage
+ *
+ * Writes session messages to Claude Code's local storage format:
+ * ~/.claude/projects/{encodedPath}/{sessionId}.jsonl
+ *
+ * Uses atomic file writes and handles filesystem errors gracefully.
+ */
+import { mkdir, writeFile } from 'fs/promises';
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+import { homedir } from 'os';
+import { encodeProjectPath } from '../utils/path-encoding.js';
+/**
+ * Error thrown when session writing fails
+ */
+export class SessionWriteError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionWriteError';
+    }
+}
+/**
+ * Write session messages to local Claude Code storage
+ *
+ * Creates a new session file in ~/.claude/projects/{encodedPath}/{sessionId}.jsonl
+ * with JSONL format (one JSON object per line).
+ *
+ * @param messages - Array of session messages to write
+ * @param projectPath - Absolute path to the project (e.g., "/Users/name/project")
+ * @returns Promise resolving to written file path and session ID
+ * @throws {SessionWriteError} If writing fails (permissions, disk space, etc.)
+ *
+ * @example
+ * const result = await writeSessionToLocal(messages, '/Users/name/my-project');
+ * console.log(`Written to: ${result.filePath}`);
+ */
+export async function writeSessionToLocal(messages, projectPath) {
+    try {
+        // 1. Encode project path for directory name
+        const encodedPath = encodeProjectPath(projectPath);
+        // 2. Generate new session ID for filename
+        // Note: Messages already have remapped sessionIds in their fields,
+        // but the filename needs its own unique ID
+        const sessionId = randomUUID();
+        // 3. Build target directory and file paths
+        const sessionDirectory = join(homedir(), '.claude', 'projects', encodedPath);
+        const targetPath = join(sessionDirectory, `${sessionId}.jsonl`);
+        // 4. Create directory structure (handles missing ~/.claude/projects/ gracefully)
+        await mkdir(sessionDirectory, { recursive: true });
+        // 5. Format as JSONL: one JSON object per line with trailing newline
+        const jsonlContent = messages.map((msg) => JSON.stringify(msg)).join('\n') + '\n';
+        // 6. Write file atomically
+        await writeFile(targetPath, jsonlContent, { encoding: 'utf-8' });
+        // 7. Return written file path and session ID for verification
+        return {
+            filePath: targetPath,
+            sessionId,
+        };
+    }
+    catch (error) {
+        // Handle filesystem errors with descriptive messages
+        if (error.code === 'EACCES') {
+            throw new SessionWriteError(`Permission denied: Cannot write to session directory. Check permissions for ~/.claude/projects/`, error.code);
+        }
+        if (error.code === 'ENOSPC') {
+            throw new SessionWriteError(`Disk full: Not enough space to write session file`, error.code);
+        }
+        // Generic error
+        throw new SessionWriteError(`Failed to write session: ${error.message || 'Unknown error'}`, error.code);
+    }
+}

package/dist/utils/path-encoding.js

@@ -0,0 +1,54 @@
+/**
+ * Path encoding utilities for Claude Code session directories
+ *
+ * Claude Code stores sessions in ~/.claude/projects/{encodedPath}/
+ * where paths are encoded by replacing `/` with `-` and removing leading `-`
+ *
+ * Example: /Users/name/project -> Users-name-project
+ */
+import { homedir } from 'os';
+import { join } from 'path';
+/**
+ * Encodes an absolute project path into Claude Code's directory naming format
+ *
+ * @param absolutePath - Absolute file system path (e.g., "/Users/name/project")
+ * @returns Encoded directory name (e.g., "Users-name-project")
+ *
+ * @example
+ * encodeProjectPath('/Users/name/my-project')
+ * // Returns: 'Users-name-my-project'
+ */
+export function encodeProjectPath(absolutePath) {
+    // Replace all forward slashes with dashes
+    const encoded = absolutePath.replace(/\//g, '-');
+    // Remove leading dash (from root /)
+    return encoded.startsWith('-') ? encoded.slice(1) : encoded;
+}
+/**
+ * Decodes a Claude Code directory name back to an absolute path
+ *
+ * @param encodedName - Encoded directory name (e.g., "Users-name-project")
+ * @returns Decoded absolute path (e.g., "/Users/name/project")
+ *
+ * @example
+ * decodeProjectPath('Users-name-my-project')
+ * // Returns: '/Users/name/my-project'
+ */
+export function decodeProjectPath(encodedName) {
+    // Replace all dashes with forward slashes and add leading slash
+    return '/' + encodedName.replace(/-/g, '/');
+}
+/**
+ * Gets the full session directory path for a project
+ *
+ * @param projectPath - Absolute project path
+ * @returns Full path to ~/.claude/projects/{encodedPath}
+ *
+ * @example
+ * getSessionDirectory('/Users/name/my-project')
+ * // Returns: '/Users/name/.claude/projects/Users-name-my-project'
+ */
+export function getSessionDirectory(projectPath) {
+    const encoded = encodeProjectPath(projectPath);
+    return join(homedir(), '.claude', 'projects', encoded);
+}

package/dist/utils/uuid-mapper.js

@@ -0,0 +1,73 @@
+/**
+ * UUID remapper for session import with collision avoidance
+ *
+ * Provides consistent UUID remapping to avoid conflicts when importing
+ * sessions into local Claude Code storage. Maintains parent-child
+ * relationships through consistent mapping.
+ */
+import { randomUUID } from 'crypto';
+/**
+ * Maps original UUIDs to new UUIDs consistently
+ *
+ * Ensures that the same original UUID always maps to the same new UUID
+ * within a session import operation. This preserves message threading
+ * and parent-child relationships.
+ */
+export class UUIDMapper {
+    map;
+    constructor() {
+        this.map = new Map();
+    }
+    /**
+     * Remap a UUID to a new collision-free UUID
+     *
+     * @param originalUuid - The original UUID to remap (or null)
+     * @returns A new UUID that consistently maps from the original, or null if input is null
+     *
+     * @example
+     * const mapper = new UUIDMapper();
+     * const newUuid1 = mapper.remap('abc-123'); // Generates new UUID
+     * const newUuid2 = mapper.remap('abc-123'); // Returns same UUID as newUuid1
+     * mapper.remap(null); // Returns null
+     */
+    remap(originalUuid) {
+        // Handle null gracefully (used for root messages with no parent)
+        if (originalUuid === null) {
+            return null;
+        }
+        // Check if we've already mapped this UUID
+        const existing = this.map.get(originalUuid);
+        if (existing) {
+            return existing;
+        }
+        // Generate a new UUID and cache the mapping
+        const newUuid = randomUUID();
+        this.map.set(originalUuid, newUuid);
+        return newUuid;
+    }
+    /**
+     * Remap all UUIDs in a session message
+     *
+     * Creates an immutable copy of the message with remapped uuid, sessionId,
+     * and parentUuid fields. Preserves all other fields unchanged.
+     *
+     * @param message - The original session message
+     * @returns A new message with remapped UUIDs (original unchanged)
+     *
+     * @example
+     * const mapper = new UUIDMapper();
+     * const original = { type: 'user', uuid: 'abc', sessionId: '123', parentUuid: null, ... };
+     * const remapped = mapper.remapMessage(original);
+     * // original is unchanged, remapped has new UUIDs
+     */
+    remapMessage(message) {
+        // Create immutable copy with remapped UUID fields
+        // Spread operator preserves all other fields (type, message, cwd, etc.)
+        return {
+            ...message,
+            uuid: this.remap(message.uuid),
+            sessionId: this.remap(message.sessionId),
+            parentUuid: this.remap(message.parentUuid),
+        };
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "claude-session-share",
+  "version": "1.0.0",
+  "description": "MCP server for sharing Claude Code sessions via GitHub Gist with privacy protection",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-session-share": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "claude",
+    "claude-code",
+    "session-sharing",
+    "github-gist",
+    "privacy",
+    "conversation-export",
+    "ai-tools"
+  ],
+  "author": "Omkar Kovvali <okovvali5@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OmkarKovvali/claude-session-share.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OmkarKovvali/claude-session-share/issues"
+  },
+  "homepage": "https://github.com/OmkarKovvali/claude-session-share#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "octokit": "^5.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.16"
+  }
+}