session-slides 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Brandon J.P. Lambert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# session-slides
+
+Convert Claude Code session transcripts into navigable HTML slide presentations.
+
+## Installation
+
+```bash
+npm install -g session-slides
+```
+
+Requires Python 3.8 or later.
+
+## Usage
+
+```bash
+# Generate slides from the current project's most recent session
+session-slides
+
+# Open in browser immediately
+session-slides --open
+
+# Generate from a specific session file
+session-slides --from ~/.claude/projects/.../session.jsonl
+
+# Custom title and output path
+session-slides --title "Building the Auth System" --output slides.html
+```
+
+Output defaults to `./session-slides/{timestamp}.html` in your current directory. Each run is preserved.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--from PATH` | Path to session JSONL file (auto-detects if omitted) |
+| `--output PATH` | Output HTML file path (default: `./session-slides/{timestamp}.html`) |
+| `--title TEXT` | Custom presentation title |
+| `--open` | Open in browser after generation |
+| `--ai-titles` | Use Ollama for slide titles (requires local Ollama) |
+| `--clean` | Remove previous timestamped output files |
+| `--verbose` | Enable verbose output |
+
+## Output
+
+Generates a self-contained HTML file with:
+
+- Title slide with session metadata
+- One slide per conversation turn
+- Intelligent titles extracted from your prompts
+- Tool usage indicators (Read, Write, Bash, etc.)
+- Code blocks with syntax highlighting
+- Summary slide with statistics
+
+The HTML has no external dependencies and works offline.
+
+## How It Works
+
+1. Parses Claude Code's JSONL session format
+2. Extracts conversation turns and tool usage
+3. Generates titles using pattern matching (390+ action verbs)
+4. Builds a responsive HTML presentation with keyboard navigation
+
+## Session Files
+
+Claude Code stores sessions in `~/.claude/projects/`. Each project directory contains JSONL files with your conversation history. The tool automatically finds the most recent session for your current working directory.
+
+## Requirements
+
+- Node.js 14+
+- Python 3.8+
+
+## License
+
+MIT

package/bin/session-slides.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+/**
+ * session-slides CLI
+ *
+ * Node.js wrapper that invokes the Python session-slides tool.
+ * Handles cross-platform Python detection and argument passthrough.
+ */
+
+'use strict';
+
+const spawn = require('cross-spawn');
+const path = require('path');
+const fs = require('fs');
+
+const SCRIPT_NAME = 'generate_slides.py';
+const MIN_PYTHON_VERSION = [3, 8];
+
+/**
+ * Parse Python version string into [major, minor] array.
+ * @param {string} versionOutput - Output from `python --version`
+ * @returns {number[]|null} - [major, minor] or null if parsing fails
+ */
+function parsePythonVersion(versionOutput) {
+  const match = versionOutput.match(/Python\s+(\d+)\.(\d+)/i);
+  if (match) {
+    return [parseInt(match[1], 10), parseInt(match[2], 10)];
+  }
+  return null;
+}
+
+/**
+ * Check if a Python version meets minimum requirements.
+ * @param {number[]} version - [major, minor]
+ * @returns {boolean}
+ */
+function meetsMinVersion(version) {
+  if (!version) return false;
+  if (version[0] > MIN_PYTHON_VERSION[0]) return true;
+  if (version[0] < MIN_PYTHON_VERSION[0]) return false;
+  return version[1] >= MIN_PYTHON_VERSION[1];
+}
+
+/**
+ * Attempt to detect a working Python 3 executable.
+ * @returns {{cmd: string, args: string[]}|null} - Command and args, or null if not found
+ */
+function detectPython() {
+  // Allow environment variable override
+  const envPython = process.env.SESSION_SLIDES_PYTHON || process.env.PYTHON3;
+  if (envPython) {
+    return { cmd: envPython, args: [] };
+  }
+
+  // Platform-specific candidate order
+  const isWindows = process.platform === 'win32';
+  const candidates = isWindows
+    ? [
+        { cmd: 'python', args: [] },
+        { cmd: 'python3', args: [] },
+        { cmd: 'py', args: ['-3'] }
+      ]
+    : [
+        { cmd: 'python3', args: [] },
+        { cmd: 'python', args: [] }
+      ];
+
+  for (const candidate of candidates) {
+    try {
+      const result = spawn.sync(candidate.cmd, [...candidate.args, '--version'], {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        timeout: 5000
+      });
+
+      if (result.status === 0) {
+        const output = (result.stdout || result.stderr || '').toString();
+        const version = parsePythonVersion(output);
+
+        if (meetsMinVersion(version)) {
+          return candidate;
+        }
+      }
+    } catch (e) {
+      // Command not found, continue to next candidate
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Print error message and exit.
+ * @param {string} message
+ * @param {number} code
+ */
+function exitWithError(message, code = 1) {
+  console.error(`\x1b[31mError:\x1b[0m ${message}`);
+  process.exit(code);
+}
+
+/**
+ * Print help for Python installation.
+ */
+function printPythonHelp() {
+  console.error(`
+\x1b[33mPython ${MIN_PYTHON_VERSION.join('.')}+ is required but was not found.\x1b[0m
+
+Install Python:
+  macOS:   brew install python3
+  Ubuntu:  sudo apt install python3
+  Windows: https://www.python.org/downloads/
+
+Or set SESSION_SLIDES_PYTHON environment variable to your Python path.
+`);
+}
+
+/**
+ * Main entry point.
+ */
+function main() {
+  // Detect Python
+  const python = detectPython();
+
+  if (!python) {
+    printPythonHelp();
+    process.exit(1);
+  }
+
+  // Locate Python script
+  const scriptPath = path.join(__dirname, '..', 'scripts', SCRIPT_NAME);
+
+  if (!fs.existsSync(scriptPath)) {
+    exitWithError(`Python script not found: ${scriptPath}\n\nThis may indicate a corrupt installation. Try reinstalling:\n  npm uninstall -g session-slides && npm install -g session-slides`);
+  }
+
+  // Build arguments: python args + script path + user args
+  const args = [...python.args, scriptPath, ...process.argv.slice(2)];
+
+  // Spawn Python process with inherited stdio for proper terminal handling
+  const child = spawn(python.cmd, args, {
+    stdio: 'inherit',
+    windowsHide: false
+  });
+
+  // Handle spawn errors
+  child.on('error', (err) => {
+    if (err.code === 'ENOENT') {
+      exitWithError(`Could not execute Python: ${python.cmd}`);
+    } else {
+      exitWithError(`Failed to start Python: ${err.message}`);
+    }
+  });
+
+  // Propagate exit code
+  child.on('close', (code) => {
+    process.exit(code || 0);
+  });
+
+  // Forward termination signals to child process
+  const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  for (const signal of signals) {
+    process.on(signal, () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    });
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "session-slides",
+  "version": "0.2.0",
+  "description": "Convert Claude Code session transcripts into navigable HTML slide presentations",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "slides",
+    "presentation",
+    "session",
+    "jsonl",
+    "html",
+    "cli"
+  ],
+  "homepage": "https://github.com/bjpl/session-slides",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bjpl/session-slides.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bjpl/session-slides/issues"
+  },
+  "license": "MIT",
+  "author": "Brandon J.P. Lambert",
+  "bin": {
+    "session-slides": "./bin/session-slides.js"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "dependencies": {
+    "cross-spawn": "^7.0.3"
+  }
+}

package/scripts/__init__.py

@@ -0,0 +1,54 @@
+"""
+Session Slides Scripts Package
+
+This package contains the core modules for parsing Claude Code sessions
+and generating presentation slides.
+"""
+
+from .parser import (
+    # Data classes
+    ToolUse,
+    ContentBlock,
+    Turn,
+    Session,
+    # Core parsing functions
+    parse_jsonl,
+    extract_turns,
+    load_session,
+    # Session finding
+    find_current_session,
+    find_all_sessions,
+    # Path utilities
+    encode_path,
+    decode_path,
+    get_project_path_from_session,
+    # Summary
+    get_session_summary,
+    # Constants
+    CLAUDE_PROJECTS_DIR,
+)
+
+__all__ = [
+    # Data classes
+    "ToolUse",
+    "ContentBlock",
+    "Turn",
+    "Session",
+    # Core parsing functions
+    "parse_jsonl",
+    "extract_turns",
+    "load_session",
+    # Session finding
+    "find_current_session",
+    "find_all_sessions",
+    # Path utilities
+    "encode_path",
+    "decode_path",
+    "get_project_path_from_session",
+    # Summary
+    "get_session_summary",
+    # Constants
+    "CLAUDE_PROJECTS_DIR",
+]
+
+__version__ = "0.1.0"

package/scripts/generate_slides.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""
+Session Slides Generator CLI
+
+Converts Claude Code session JSONL files into navigable HTML slide presentations.
+
+Usage:
+    python generate_slides.py [options]
+
+Options:
+    --from PATH      Session JSONL file (auto-detects if omitted)
+    --output PATH    Output HTML file (default: ./session-slides/{timestamp}.html)
+    --title TEXT     Custom presentation title
+    --open           Open in browser after generation
+    --ai-titles      Use Ollama for title generation (requires ollama)
+    --clean          Remove previous output files before generating
+"""
+
+import argparse
+import sys
+import webbrowser
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# Import from sibling modules
+from parser import Session, Turn, extract_turns, find_current_session, load_session
+from titles import generate_turn_title, generate_continued_title, generate_title_ollama
+from truncation import (
+    TruncationConfig,
+    truncate_user_prompt,
+    truncate_prose,
+    truncate_code_block,
+    format_tool_use,
+)
+from html_generator import generate_html
+
+
+def print_progress(message: str, end: str = "\n") -> None:
+    """Print progress message to terminal."""
+    print(f"[*] {message}", end=end, flush=True)
+
+
+def print_success(message: str) -> None:
+    """Print success message to terminal."""
+    print(f"[✓] {message}")
+
+
+def print_error(message: str) -> None:
+    """Print error message to terminal."""
+    print(f"[✗] {message}", file=sys.stderr)
+
+
+def generate_titles_for_session(session: Session, use_ai: bool = False) -> dict[int, str]:
+    """Generate titles for all turns in a session."""
+    titles = {}
+
+    for turn in session.turns:
+        if turn.is_user_message():
+            prompt = turn.get_text_content()
+            if use_ai:
+                # Try AI first, fall back to heuristic
+                ai_title = generate_title_ollama(prompt)
+                if ai_title:
+                    titles[turn.number if hasattr(turn, 'number') else len(titles) + 1] = ai_title
+                else:
+                    titles[turn.number if hasattr(turn, 'number') else len(titles) + 1] = generate_turn_title(prompt, len(titles) + 1)
+            else:
+                titles[turn.number if hasattr(turn, 'number') else len(titles) + 1] = generate_turn_title(prompt, len(titles) + 1)
+
+    return titles
+
+
+def session_to_dict(session: Session) -> dict:
+    """
+    Convert Session object to dict format expected by html_generator.
+
+    Uses get_conversation_pairs() to combine user prompts with assistant responses
+    into the format expected by generate_turn_slide():
+        {number, prompt, response, tools_used, files_modified, title, timestamp}
+
+    Applies truncation to keep slide content concise.
+    """
+    turns_data = []
+    config = TruncationConfig()
+
+    # Use get_conversation_pairs() to pair user turns with assistant responses
+    conversation_pairs = session.get_conversation_pairs()
+
+    for turn_num, (user_turn, assistant_responses) in enumerate(conversation_pairs, 1):
+        # Get and truncate user prompt
+        raw_prompt = user_turn.get_text_content()
+        prompt = truncate_user_prompt(raw_prompt, config)
+
+        # Combine all assistant responses
+        response_parts = []
+        tools_used = []
+        files_modified = []
+
+        for assistant_turn in assistant_responses:
+            # Get text content
+            raw_response = assistant_turn.get_text_content()
+            if raw_response:
+                # Truncate prose content
+                truncated_response = truncate_prose(raw_response, config)
+                response_parts.append(truncated_response)
+
+            # Collect tool uses
+            for tool_use in assistant_turn.get_tool_uses():
+                # Format tool use as a concise description
+                tool_desc = format_tool_use(tool_use.name, tool_use.input)
+                tools_used.append(tool_desc)
+
+                # Track file modifications from tool uses
+                if tool_use.name in ('Write', 'Edit', 'NotebookEdit'):
+                    file_path = tool_use.input.get('file_path', '')
+                    if file_path:
+                        action = 'created' if tool_use.name == 'Write' else 'modified'
+                        files_modified.append({
+                            'path': file_path,
+                            'action': action,
+                        })
+
+        # Combine response parts
+        response = '\n\n'.join(response_parts) if response_parts else ''
+
+        # Generate title for this turn
+        title = generate_turn_title(raw_prompt, turn_num)
+
+        turns_data.append({
+            'number': turn_num,
+            'prompt': prompt,
+            'response': response,
+            'tools_used': tools_used,
+            'files_modified': files_modified,
+            'title': title,
+            'timestamp': user_turn.timestamp.isoformat() if user_turn.timestamp else None,
+        })
+
+    return {
+        'session_id': session.session_id,
+        'project_path': session.project_path,
+        'turns': turns_data,
+        'metadata': {
+            'timestamp': session.start_time.isoformat() if session.start_time else None,
+        },
+        'created_at': session.turns[0].timestamp.isoformat() if session.turns and session.turns[0].timestamp else None,
+        'total_turns': len(turns_data),
+    }
+
+
+def main() -> int:
+    """Main entry point for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="generate_slides",
+        description="Convert Claude Code session files into HTML slide presentations",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python generate_slides.py --from session.jsonl
+  python generate_slides.py --from session.jsonl --output slides.html --title "My Session"
+  python generate_slides.py --from session.jsonl --ai-titles --open
+  python generate_slides.py  # Auto-detect latest session file
+        """,
+    )
+
+    parser.add_argument(
+        "--from",
+        dest="input_file",
+        type=str,
+        metavar="PATH",
+        help="Path to session JSONL file (auto-detects if not specified)",
+    )
+
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=str,
+        metavar="PATH",
+        help="Output HTML file path (default: ./session-slides/{timestamp}.html)",
+    )
+
+    parser.add_argument(
+        "--title",
+        "-t",
+        type=str,
+        metavar="TEXT",
+        help="Custom title for the presentation",
+    )
+
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        help="Open the generated HTML in default browser",
+    )
+
+    parser.add_argument(
+        "--ai-titles",
+        action="store_true",
+        help="Use Ollama AI to generate slide titles (requires local Ollama)",
+    )
+
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Enable verbose output",
+    )
+
+    parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Remove previous output files before generating",
+    )
+
+    args = parser.parse_args()
+
+    # Step 1: Find or load session file
+    if args.input_file:
+        input_path = Path(args.input_file)
+        if not input_path.exists():
+            print_error(f"Session file not found: {input_path}")
+            return 1
+        print_progress(f"Loading session: {input_path}")
+    else:
+        print_progress("Searching for latest session...")
+        input_path = find_current_session()
+        if input_path is None:
+            print_error("No session file found for current directory.")
+            print_error("Use --from to specify a session file path.")
+            return 1
+        print_success(f"Found session: {input_path}")
+
+    # Step 2: Parse session file
+    try:
+        session = extract_turns(input_path)
+    except Exception as e:
+        print_error(f"Failed to parse session: {e}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+    if not session.turns:
+        print_error("Session contains no conversation turns")
+        return 1
+
+    user_turns = len([t for t in session.turns if t.is_user_message()])
+    print_success(f"Parsed {len(session.turns)} messages ({user_turns} user turns)")
+
+    # Step 3: Convert to dict format and generate titles
+    if args.ai_titles:
+        print_progress("Generating AI titles with Ollama...")
+    else:
+        print_progress("Generating heuristic titles...")
+
+    session_dict = session_to_dict(session)
+    print_success(f"Generated {session_dict['total_turns']} slide titles")
+
+    # Step 4: Generate HTML
+    presentation_title = args.title or f"Session: {session.session_id[:8] if session.session_id else 'Claude Code'}"
+    print_progress("Building HTML presentation...")
+
+    try:
+        html_content = generate_html(session_dict, title=presentation_title)
+    except Exception as e:
+        print_error(f"Failed to generate HTML: {e}")
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+    # Step 5: Write output
+    if args.output:
+        output_path = Path(args.output)
+    else:
+        # Default: write to ./session-slides/ in the current working directory
+        # Each run gets a timestamped filename to preserve history
+        output_dir = Path.cwd() / "session-slides"
+        output_dir.mkdir(exist_ok=True)
+
+        # Clean previous output files if requested
+        if args.clean:
+            old_files = list(output_dir.glob("*.html"))
+            if old_files:
+                for old_file in old_files:
+                    old_file.unlink()
+                print_progress(f"Cleaned {len(old_files)} previous output file(s)")
+
+        timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+        output_path = output_dir / f"{timestamp}.html"
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        output_path.write_text(html_content, encoding="utf-8")
+    except IOError as e:
+        print_error(f"Failed to write output: {e}")
+        return 1
+
+    print_success(f"Generated: {output_path.absolute()}")
+
+    # Step 6: Optionally open in browser
+    if args.open:
+        print_progress("Opening in browser...")
+        try:
+            webbrowser.open(f"file://{output_path.absolute()}")
+        except Exception as e:
+            print_error(f"Could not open browser: {e}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())