claude-session-share 1.1.0 → 1.2.0

package/README.md

@@ -2,18 +2,15 @@
 
 MCP server for sharing Claude Code sessions via GitHub Gist with automatic privacy protection.
 
-Share your Claude Code conversations while keeping private data safe. Export sessions to shareable GitHub Gist links and import them back—all through natural language or CLI.
-
 [![npm version](https://badge.fury.io/js/claude-session-share.svg)](https://www.npmjs.com/package/claude-session-share)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **One-Click Sharing** - Export sessions to GitHub Gist with a simple command
+- **One-Click Sharing** - Export sessions to GitHub Gist through natural language
 - **Privacy First** - Automatically strips thinking blocks, sanitizes paths, and redacts secrets
 - **Seamless Import** - Import shared sessions that work exactly like native Claude Code sessions
-- **Natural Language** - Just ask Claude to "share my session" or "import from [link]"
-- **Full Compatibility** - Imported sessions appear in `claude --resume` and preserve conversation context
+- **Full Compatibility** - Imported sessions appear in `claude --resume`
 
 ## Installation
 
@@ -23,27 +20,16 @@ Share your Claude Code conversations while keeping private data safe. Export ses
 - Claude Code CLI
 - GitHub Personal Access Token with `gist` scope
 
-### Install via npm
-
-```bash
-npm install -g claude-session-share
-```
-
 ### Setup GitHub Token
 
 1. Go to [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)
 2. Click "Generate new token (classic)"
-3. Give it a name like "Claude Session Share"
-4. Check the **`gist`** scope
-5. Generate and copy the token
+3. Check the **`gist`** scope
+4. Generate and copy the token
 
-## Configuration
+### Configure MCP Server
 
-Add the MCP server to your Claude Code configuration.
-
-### User Config (Recommended)
-
-Create or edit `~/.claude/mcp.json`:
+Add to `~/.claude/mcp.json`:
 
 ```json
 {
@@ -59,21 +45,17 @@ Create or edit `~/.claude/mcp.json`:
 }
 ```
 
-### Project-Specific Config
-
-Create `.mcp.json` in your project directory with the same structure.
-
 ### Verify Installation
 
 ```bash
 claude  # Start Claude Code
-# Then type: /mcp
+# Type: /mcp
 # You should see "claude-session-share" in the list
 ```
 
 ## Usage
 
-### Natural Language (via MCP)
+### Share a Session
 
 In any Claude Code conversation:
 
@@ -84,47 +66,23 @@ In any Claude Code conversation:
 Claude will:
 1. Find your current session
 2. Remove thinking blocks and sanitize paths/secrets
-3. Upload to a secret (unlisted) GitHub Gist
+3. Upload to a secret GitHub Gist
 4. Return a shareable link
 
-To import a shared session:
+### Import a Session
 
 ```
-"Import this session: https://gist.github.com/username/abc123..."
-```
-
-### Command Line (Standalone CLI)
-
-#### Share a session
-
-```bash
-# Share most recent session
-npx claude-session-share share
-
-# Share specific session file
-npx claude-session-share share --session-path ~/.claude/projects/abc/session.jsonl
-```
-
-#### Import a session
-
-```bash
-# Import to current directory
-npx claude-session-share import https://gist.github.com/user/abc123
-
-# Import to specific directory
-npx claude-session-share import abc123 --project-path /Users/name/project
+"Import this session: https://gist.github.com/username/abc123"
 ```
 
-### Resuming an Imported Session
+### Resume an Imported Session
 
 ```bash
-cd your-project-directory
 claude --resume
 # Select the imported session from the list
 ```
 
-Or resume directly with the session ID:
-
+Or directly:
 ```bash
 claude --resume <session-id>
 ```
@@ -133,132 +91,46 @@ claude --resume <session-id>
 
 Every shared session is automatically sanitized:
 
-### What Gets Removed/Sanitized
-
-- **Thinking Blocks** - Internal reasoning stripped completely
-- **Absolute Paths** - `/Users/you/project/file.ts` → `file.ts`
-- **API Keys** - `sk_test_abc123`, `ghp_token`, AWS keys → `[REDACTED]`
-- **Tokens** - Bearer tokens, OAuth tokens → `[REDACTED]`
-- **Secrets** - Environment variables, passwords (key=value format) → `[REDACTED]`
-
-### What Gets Preserved
+### Removed/Sanitized
+- Thinking blocks (internal reasoning)
+- Absolute paths → relative paths
+- API keys, tokens, secrets → `[REDACTED]`
 
+### Preserved
 - Conversation flow and context
-- Code examples and explanations
-- File names and relative paths
+- Code examples
+- Relative file paths
 - Tool use history
-- UUIDs and message chains (remapped on import)
-
-### Known Limitations
 
-- Passwords in connection strings (e.g., `postgresql://user:pass@host/db`) are not detected
-- Secrets in natural language (not key=value format) may not be redacted
-
-## MCP Tools Reference
+## MCP Tools
 
 ### `share_session`
-
-Exports the current session to GitHub Gist.
-
-**Parameters:**
-- `sessionPath` (optional) - Path to session file (defaults to most recent)
-
-**Returns:**
-- `gistUrl` - Shareable GitHub Gist URL
-- `messageCount` - Number of messages exported
+Exports current session to GitHub Gist.
 
 ### `import_session`
+Imports session from GitHub Gist URL.
+
+## Troubleshooting
 
-Imports a session from a GitHub Gist.
+### "Not authenticated" Error
+Ensure `GITHUB_TOKEN` is set in MCP configuration.
 
-**Parameters:**
-- `gistUrl` - GitHub Gist URL or bare gist ID
-- `projectPath` - Local project directory for import
+### Imported Session Doesn't Appear
+Restart Claude Code to refresh the session list.
 
-**Returns:**
-- `sessionPath` - Path to imported session file
-- `sessionId` - New session ID
-- `messageCount` - Number of messages imported
+### MCP Server Not Listed
+Verify `~/.claude/mcp.json` and restart Claude Code.
 
 ## Development
 
-### Setup
-
 ```bash
 git clone https://github.com/OmkarKovvali/claude-session-share.git
 cd claude-session-share
 npm install
-```
-
-### Build
-
-```bash
 npm run build
-```
-
-### Run Tests
-
-```bash
 npm test
-# 420 tests
-```
-
-### Project Structure
-
-```
-claude-session-share/
-├── src/
-│   ├── index.ts                 # MCP server entry point
-│   ├── cli.ts                   # CLI entry point
-│   ├── gist/                    # GitHub Gist integration
-│   ├── sanitization/            # Privacy protection
-│   ├── services/                # Share/import orchestration
-│   ├── session/                 # Session read/write
-│   └── utils/                   # UUID remapping, path encoding
-├── dist/                        # Compiled output
-└── package.json
-```
-
-## Troubleshooting
-
-### "Not authenticated" Error
-
-Ensure `GITHUB_TOKEN` is set in MCP configuration:
-```json
-"env": {
-  "GITHUB_TOKEN": "ghp_your_token_here"
-}
 ```
 
-### "No sessions found" Error
-
-Ensure you're in a directory with an active Claude Code session. Sessions are stored in `~/.claude/projects/`.
-
-### Imported Session Doesn't Appear
-
-After importing, restart Claude Code to refresh the session list. The session file should be in `~/.claude/projects/-{encoded-path}/`.
-
-### MCP Server Not Listed
-
-Verify your MCP configuration:
-```bash
-cat ~/.claude/mcp.json
-```
-Then restart Claude Code.
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes
-4. Push to the branch
-5. Open a Pull Request
-
 ## License
 
 MIT © Omkar Kovvali
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/OmkarKovvali/claude-session-share/issues)
-- **Email**: okovvali5@gmail.com

package/dist/index.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from 'url';
 // Create the MCP server instance
 const server = new Server({
     name: "claude-session-share",
-    version: "1.1.0",
+    version: "1.2.0",
 }, {
     capabilities: {
         tools: {},

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "claude-session-share",
-  "version": "1.1.0",
+  "version": "1.2.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/cli.js"
-  },
   "files": [
     "dist/**/*",
     "README.md",

package/dist/__tests__/cli.test.js

@@ -1,120 +0,0 @@
-/**
- * Tests for CLI entry point
- *
- * Validates command parsing and integration with services
- */
-import { describe, it, expect, vi } from 'vitest';
-import { uploadSession } from '../services/session-uploader.js';
-import { importSession } from '../services/session-importer.js';
-// Mock the services at module level
-vi.mock('../services/session-uploader.js', () => ({
-    uploadSession: vi.fn(),
-}));
-vi.mock('../services/session-importer.js', () => ({
-    importSession: vi.fn(),
-}));
-// Mock fs/promises for findMostRecentSession
-vi.mock('fs/promises', async () => {
-    const actual = await vi.importActual('fs/promises');
-    return {
-        ...actual,
-        readdir: vi.fn(),
-        stat: vi.fn(),
-    };
-});
-describe('CLI argument parsing', () => {
-    it('should parse share command with session path', () => {
-        // Test that share command with --session-path flag works
-        const args = ['share', '--session-path', '/path/to/session.jsonl'];
-        // Find the session-path value
-        const pathIndex = args.indexOf('--session-path');
-        const sessionPath = pathIndex !== -1 && pathIndex + 1 < args.length
-            ? args[pathIndex + 1]
-            : null;
-        expect(sessionPath).toBe('/path/to/session.jsonl');
-    });
-    it('should parse share command without session path', () => {
-        const args = ['share'];
-        const pathIndex = args.indexOf('--session-path');
-        const sessionPath = pathIndex !== -1 && pathIndex + 1 < args.length
-            ? args[pathIndex + 1]
-            : null;
-        expect(sessionPath).toBeNull();
-    });
-    it('should parse import command with gist URL and default project path', () => {
-        // Simulate: node cli.js import https://gist...
-        // After "import" is consumed, remaining args are:
-        const argsAfterCommand = ['https://gist.github.com/user/abc123'];
-        const gistUrl = argsAfterCommand[0];
-        const pathIndex = argsAfterCommand.indexOf('--project-path');
-        const projectPath = pathIndex !== -1 && pathIndex + 1 < argsAfterCommand.length
-            ? argsAfterCommand[pathIndex + 1]
-            : process.cwd();
-        expect(gistUrl).toBe('https://gist.github.com/user/abc123');
-        expect(projectPath).toBe(process.cwd());
-    });
-    it('should parse import command with project-path flag', () => {
-        // Simulate: node cli.js import abc123 --project-path /tmp/test
-        const argsAfterCommand = ['abc123', '--project-path', '/tmp/test'];
-        const gistUrl = argsAfterCommand[0];
-        const pathIndex = argsAfterCommand.indexOf('--project-path');
-        const projectPath = pathIndex !== -1 && pathIndex + 1 < argsAfterCommand.length
-            ? argsAfterCommand[pathIndex + 1]
-            : process.cwd();
-        expect(gistUrl).toBe('abc123');
-        expect(projectPath).toBe('/tmp/test');
-    });
-    it('should handle missing gist URL in import command', () => {
-        // Simulate: node cli.js import (no URL provided)
-        const argsAfterCommand = [];
-        const gistUrl = argsAfterCommand[0];
-        expect(gistUrl).toBeUndefined();
-    });
-});
-describe('CLI service integration', () => {
-    it('uploadSession service should be importable', () => {
-        expect(uploadSession).toBeDefined();
-        expect(typeof uploadSession).toBe('function');
-    });
-    it('importSession service should be importable', () => {
-        expect(importSession).toBeDefined();
-        expect(typeof importSession).toBe('function');
-    });
-    it('uploadSession mock can be configured', () => {
-        vi.mocked(uploadSession).mockResolvedValue('https://gist.github.com/test/123');
-        expect(vi.mocked(uploadSession)).toBeDefined();
-    });
-    it('importSession mock can be configured', () => {
-        vi.mocked(importSession).mockResolvedValue({
-            sessionPath: '/path/to/session.jsonl',
-            sessionId: 'test-id',
-            messageCount: 10,
-            projectPath: '/test',
-        });
-        expect(vi.mocked(importSession)).toBeDefined();
-    });
-});
-describe('CLI usage validation', () => {
-    it('should have share and import as valid commands', () => {
-        const validCommands = ['share', 'import'];
-        expect(validCommands).toContain('share');
-        expect(validCommands).toContain('import');
-        expect(validCommands).not.toContain('unknown');
-    });
-    it('should validate share command structure', () => {
-        // share command can have optional --session-path
-        const shareArgs1 = ['share'];
-        const shareArgs2 = ['share', '--session-path', '/path'];
-        expect(shareArgs1[0]).toBe('share');
-        expect(shareArgs2[0]).toBe('share');
-        expect(shareArgs2.includes('--session-path')).toBe(true);
-    });
-    it('should validate import command structure', () => {
-        // import command requires gist URL, optional --project-path
-        const importArgsAfterCommand1 = ['https://gist.github.com/user/id'];
-        const importArgsAfterCommand2 = ['abc123', '--project-path', '/path'];
-        expect(importArgsAfterCommand1[0]).toBe('https://gist.github.com/user/id');
-        expect(importArgsAfterCommand2[0]).toBe('abc123');
-        expect(importArgsAfterCommand2.includes('--project-path')).toBe(true);
-    });
-});

package/dist/cli.js

@@ -1,195 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI entry point for Claude Session Share
- *
- * Provides standalone command-line interface:
- * - share: Upload session to Gist
- * - import: Download session from Gist
- *
- * Also detects MCP mode when stdin is piped (no TTY).
- */
-import { uploadSession } from './services/session-uploader.js';
-import { importSession } from './services/session-importer.js';
-import { stdin } from 'process';
-import { homedir } from 'os';
-import { join } from 'path';
-import { readdir, stat } from 'fs/promises';
-import { realpathSync } from 'fs';
-import { fileURLToPath } from 'url';
-/**
- * Find the most recent session file
- * Searches ~/.claude/projects/ for all session files and returns the most recently modified one
- */
-async function findMostRecentSession() {
-    const projectsDir = join(homedir(), '.claude', 'projects');
-    try {
-        // Get all subdirectories in ~/.claude/projects/
-        const entries = await readdir(projectsDir, { withFileTypes: true });
-        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-        let mostRecentFile = null;
-        let mostRecentTime = 0;
-        // Search each project directory for session files
-        for (const dir of dirs) {
-            const dirPath = join(projectsDir, dir);
-            try {
-                const files = await readdir(dirPath);
-                for (const file of files) {
-                    if (file.endsWith('.jsonl')) {
-                        const filePath = join(dirPath, file);
-                        const stats = await stat(filePath);
-                        if (stats.mtimeMs > mostRecentTime) {
-                            mostRecentTime = stats.mtimeMs;
-                            mostRecentFile = filePath;
-                        }
-                    }
-                }
-            }
-            catch (err) {
-                // Skip directories we can't read
-                continue;
-            }
-        }
-        return mostRecentFile;
-    }
-    catch (err) {
-        throw new Error(`Failed to find sessions: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-/**
- * Parse command-line arguments for share command
- * Returns session path or null for auto-detect
- */
-function parseShareArgs(args) {
-    // Look for --session-path flag
-    const pathIndex = args.indexOf('--session-path');
-    if (pathIndex !== -1 && pathIndex + 1 < args.length) {
-        return args[pathIndex + 1];
-    }
-    return null; // Auto-detect most recent
-}
-/**
- * Parse command-line arguments for import command
- * Returns { gistUrl, projectPath } or throws if invalid
- */
-function parseImportArgs(args) {
-    // First positional arg after "import" is gist URL
-    const gistUrl = args[0];
-    if (!gistUrl) {
-        throw new Error('Missing required argument: gist-url\nUsage: import <gist-url> [--project-path <path>]');
-    }
-    // Look for --project-path flag, default to cwd
-    const pathIndex = args.indexOf('--project-path');
-    const projectPath = pathIndex !== -1 && pathIndex + 1 < args.length
-        ? args[pathIndex + 1]
-        : process.cwd();
-    return { gistUrl, projectPath };
-}
-/**
- * Display usage information
- */
-function showUsage() {
-    console.log(`
-Claude Session Share - CLI for sharing Claude Code sessions
-
-USAGE:
-  claude-session-share <command> [options]
-
-COMMANDS:
-  share                     Share most recent session to GitHub Gist
-  share --session-path PATH Share specific session file
-  import <gist-url>         Import session from GitHub Gist to current directory
-  import <gist-url> --project-path PATH
-                            Import session to specific directory
-
-EXAMPLES:
-  # Share most recent session
-  claude-session-share share
-
-  # Share specific session
-  claude-session-share share --session-path ~/.claude/projects/abc/session.jsonl
-
-  # Import session to current directory
-  claude-session-share import https://gist.github.com/user/abc123
-
-  # Import to specific directory
-  claude-session-share import abc123 --project-path /Users/name/project
-
-ENVIRONMENT:
-  GITHUB_TOKEN    Required for both share and import operations
-                  Get token at https://github.com/settings/tokens
-                  Needs 'gist' scope for creating/reading gists
-`);
-}
-/**
- * Main CLI entry point
- */
-async function main() {
-    const args = process.argv.slice(2);
-    // If no args and stdin is not a TTY, assume MCP stdio mode
-    if (args.length === 0 && !stdin.isTTY) {
-        // Import and run MCP server
-        const { default: runMCPServer } = await import('./index.js');
-        return runMCPServer();
-    }
-    // CLI mode: require at least one argument
-    if (args.length === 0) {
-        showUsage();
-        process.exit(1);
-    }
-    const command = args[0];
-    try {
-        if (command === 'share') {
-            // Parse share arguments
-            const sessionPath = parseShareArgs(args.slice(1));
-            // Find session to share
-            const pathToShare = sessionPath || await findMostRecentSession();
-            if (!pathToShare) {
-                console.error('Error: No session files found in ~/.claude/projects/');
-                console.error('Please provide a session path with --session-path');
-                process.exit(1);
-            }
-            // Upload session
-            console.log(`Uploading session: ${pathToShare}`);
-            const gistUrl = await uploadSession(pathToShare);
-            console.log('\n✓ Session shared successfully!');
-            console.log(`\nGist URL: ${gistUrl}`);
-            console.log('\nShare this URL to give others access to the conversation.');
-        }
-        else if (command === 'import') {
-            // Parse import arguments
-            const { gistUrl, projectPath } = parseImportArgs(args.slice(1));
-            // Import session
-            console.log(`Importing session from: ${gistUrl}`);
-            console.log(`Target directory: ${projectPath}`);
-            const result = await importSession(gistUrl, projectPath);
-            console.log('\n✓ Session imported successfully!');
-            console.log(`\nSession ID: ${result.sessionId}`);
-            console.log(`Messages: ${result.messageCount}`);
-            console.log(`Location: ${result.sessionPath}`);
-            console.log(`\nUse 'claude --resume' to see imported session.`);
-        }
-        else {
-            console.error(`Error: Unknown command '${command}'`);
-            console.error('');
-            showUsage();
-            process.exit(1);
-        }
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error(`\nError: ${errorMessage}`);
-        process.exit(1);
-    }
-}
-// Export main for MCP mode, but also run if this is the entry point
-export default main;
-// Run main if this file is executed directly (not imported)
-// Need to resolve symlinks because process.argv[1] might be a symlink
-const currentFile = fileURLToPath(import.meta.url);
-const scriptFile = realpathSync(process.argv[1]);
-if (currentFile === scriptFile) {
-    main().catch((error) => {
-        console.error('Fatal error:', error);
-        process.exit(1);
-    });
-}