learn_bash_from_session_data 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # learn_bash_from_session_data
 
-Learn bash from your Claude Code sessions. Extracts commands you've used, categorizes them, and generates an interactive HTML learning resource with quizzes.
+Turn your Claude Code sessions into personalized bash lessons. This tool extracts every command you've run, enriches them with descriptions and flag breakdowns from a 402-command knowledge base, generates interactive quizzes, and produces a self-contained HTML learning resource.
 
 ## Installation
 
@@ -8,37 +8,160 @@ Learn bash from your Claude Code sessions. Extracts commands you've used, catego
 npm install -g learn_bash_from_session_data
 ```
 
-## Usage
+**Requirements:** Node.js >= 14.0.0 and Python >= 3.8
+
+## Quick Start
 
 ```bash
-# Analyze all sessions from current project
+# Generate a lesson from your current project's sessions
 learn-bash
 
-# Analyze last 5 sessions
+# Process the last 5 sessions only
 learn-bash -n 5
 
-# List available projects
+# List all available Claude Code projects
 learn-bash --list
+```
+
+The generated HTML opens automatically in your browser.
+
+## CLI Reference
+
+```
+learn-bash [options]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--sessions <count>` | `-n` | Number of recent sessions to process (default: all) |
+| `--file <path>` | `-f` | Process a specific session JSONL file |
+| `--output <path>` | `-o` | Output directory path (default: `./bash-learner-output/`) |
+| `--project <name>` | `-p` | Process sessions from a specific project by name |
+| `--list` | `-l` | List available Claude Code projects with session counts |
+| `--no-open` | | Don't auto-open the generated HTML in browser |
+| `--help` | `-h` | Show help message |
+
+### Examples
+
+```bash
+# Process a specific session file
+learn-bash --file ~/.claude/projects/my-project/abc123.jsonl
+
+# Output to a custom location without opening browser
+learn-bash -o ./my-lessons --no-open
 
-# Process specific session file
-learn-bash --file ~/.claude/projects/.../session.jsonl
+# Process sessions from a named project
+learn-bash --project "C--Users-me-my-app"
 
-# Custom output path
-learn-bash --output ./my-lessons.html
+# Process last 3 sessions, custom output
+learn-bash -n 3 -o ./review
 ```
 
-## Features
+## What You Get
+
+The tool generates a single interactive HTML file with four sections:
+
+### Commands Tab
+Every bash command you used, organized by category with:
+- Syntax-highlighted full command display
+- Flag breakdowns with descriptions (e.g., `-l` = "Long format listing with permissions, size, dates")
+- Subcommand explanations (e.g., `git add` = "Stage file contents for commit")
+- Common usage patterns from the knowledge base
+- Search, sort (by frequency, complexity, category, name), and category filtering
+
+### Lessons Tab
+Step-by-step walkthrough of commands grouped by category, with flag details and complexity indicators. Designed for sequential learning.
+
+### Quiz Tab
+20 auto-generated questions in four types:
+
+| Type | Weight | What It Tests |
+|------|--------|---------------|
+| What does this do? | 40% | Identify a command's purpose from its syntax |
+| Which flag? | 25% | Match a flag to its behavior |
+| Build the command | 20% | Construct the correct command for a task |
+| Spot the difference | 15% | Compare two similar commands |
+
+Quizzes are **session-adaptive** (based on commands you actually used), **randomized** (different questions and answer order each run), and use plausible distractors drawn from 402 real commands.
+
+### Summary Tab
+Statistics on your session: total commands, category distribution, complexity breakdown, most-used commands.
+
+## Knowledge Base
 
-- **Command Extraction**: Parses Claude Code session JSONL files
-- **Categorization**: Groups commands by category (Git, File System, Text Processing, etc.)
-- **Complexity Scoring**: Rates commands from 1-5 based on complexity
-- **Interactive Quizzes**: Test your knowledge with auto-generated quizzes
-- **Self-Contained HTML**: No external dependencies, works offline
+The built-in knowledge base powers descriptions, flag lookups, and quiz generation:
 
-## Requirements
+| Metric | Count |
+|--------|-------|
+| Commands documented | 402 |
+| Flag definitions | 1,961 |
+| Common usage patterns | 1,357 |
+| Categories | 11 |
+| Bash operators | 16 |
+| Bash concepts | 6 |
 
-- Node.js >= 14.0.0
-- Python >= 3.8
+### Categories
+
+File System, Text Processing, Git, Package Management, Process & System, Networking, Permissions, Compression, Search & Navigation, Development, Shell Builtins
+
+## How It Works
+
+```
+Claude Code session (.jsonl)
+    |
+    v
+[Parser] --> Extract bash tool_use blocks
+    |
+    v
+[Extractor] --> Split compound commands (pipes, &&, ;)
+    |
+    v
+[Analyzer] --> Categorize, score complexity (1-5), count frequency
+    |
+    v
+[Knowledge Base] --> Enrich with 402 commands, 1961 flags, 1357 patterns
+    |
+    v
+[Quiz Generator] --> 20 randomized, session-adaptive questions
+    |
+    v
+[HTML Generator] --> Self-contained interactive HTML (no dependencies)
+```
+
+## Session File Location
+
+Claude Code stores sessions at:
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.claude/projects/` |
+| Windows | `%USERPROFILE%\.claude\projects\` |
+| WSL | Auto-detected from `/mnt/c/Users/<name>/.claude/projects/` |
+
+Each project directory contains `.jsonl` session files that this tool reads.
+
+## Programmatic Usage
+
+You can also run the Python pipeline directly:
+
+```bash
+python scripts/main.py --sessions 5 --output ./output
+```
+
+Or import modules in Python:
+
+```python
+from scripts.knowledge_base import COMMAND_DB, get_flags_for_command, get_command_info
+from scripts.quiz_generator import generate_quiz_set
+from scripts.analyzer import analyze_commands
+
+# Look up a command
+info = get_command_info("grep")
+flags = get_flags_for_command("grep")
+
+# Generate quizzes from analyzed commands
+quizzes = generate_quiz_set(analyzed_commands, count=10)
+```
 
 ## License
 

package/bin/learn-bash.js

@@ -240,26 +240,29 @@ function checkPython() {
  */
 function openInBrowser(filePath) {
   const platform = os.platform();
+  const isWindows = platform === 'win32' ||
+    process.env.MSYSTEM != null ||
+    (process.env.OSTYPE && process.env.OSTYPE.includes('msys')) ||
+    isWSL();
   let cmd;
   let args;
 
-  switch (platform) {
-    case 'darwin':
-      cmd = 'open';
-      args = [filePath];
-      break;
-    case 'win32':
-      cmd = 'cmd';
-      args = ['/c', 'start', '', filePath];
-      break;
-    default:
-      // Linux and others
-      cmd = 'xdg-open';
-      args = [filePath];
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [filePath];
+  } else if (isWindows) {
+    // Works from native Windows, MSYS, Git Bash, and WSL
+    cmd = process.env.COMSPEC || 'cmd.exe';
+    args = ['/c', 'start', '', filePath.replace(/\//g, '\\')];
+  } else {
+    cmd = 'xdg-open';
+    args = [filePath];
   }
 
   try {
-    spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => {});  // Suppress async spawn errors
+    child.unref();
     return true;
   } catch (e) {
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn_bash_from_session_data",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Learn bash from your Claude Code sessions - extracts commands and generates interactive HTML lessons with 400+ commands, quizzes, and comprehensive coverage",
   "main": "bin/learn-bash.js",
   "bin": {

package/scripts/html_generator.py

@@ -12,6 +12,16 @@ from pathlib import Path
 import html
 import json
 
+try:
+    from scripts.knowledge_base import COMMAND_DB, get_flags_for_command, get_command_info
+except ImportError:
+    try:
+        from knowledge_base import COMMAND_DB, get_flags_for_command, get_command_info
+    except ImportError:
+        COMMAND_DB = {}
+        def get_flags_for_command(cmd): return {}
+        def get_command_info(cmd): return None
+
 
 def _generate_html_impl(analysis_result: dict[str, Any], quizzes: list[dict[str, Any]]) -> str:
     """
@@ -376,7 +386,7 @@ def render_commands_tab(commands: list[dict]) -> str:
         # Syntax highlighted command
         highlighted = _syntax_highlight(cmd.get("full_command", ""))
 
-        # Flags breakdown
+        # Flags breakdown with descriptions
         flags = cmd.get("flags", [])
         flags_html = ""
         if flags:
@@ -384,9 +394,27 @@ def render_commands_tab(commands: list[dict]) -> str:
             for flag in flags:
                 flag_name = html.escape(flag.get("flag", ""))
                 flag_desc = html.escape(flag.get("description", ""))
-                flags_html += f'<li><code class="flag">{flag_name}</code> - {flag_desc}</li>'
+                if flag_desc:
+                    flags_html += f'<li><code class="flag">{flag_name}</code> <span class="flag-desc">{flag_desc}</span></li>'
+                else:
+                    flags_html += f'<li><code class="flag">{flag_name}</code></li>'
             flags_html += '</ul></div>'
 
+        # Subcommand description
+        subcommand_desc = cmd.get("subcommand_desc", "")
+        subcmd_html = ""
+        if subcommand_desc:
+            subcmd_html = f'<div class="subcmd-section"><span class="subcmd-label">Subcommand:</span> {html.escape(subcommand_desc)}</div>'
+
+        # Common patterns / examples from knowledge base
+        common_patterns = cmd.get("common_patterns", [])
+        patterns_html = ""
+        if common_patterns:
+            patterns_html = '<div class="patterns-section"><h5>Common Patterns:</h5><ul class="patterns-list">'
+            for pattern in common_patterns[:5]:
+                patterns_html += f'<li><code>{html.escape(pattern)}</code></li>'
+            patterns_html += '</ul></div>'
+
         # Output preview
         output_preview = cmd.get("output_preview", "")
         output_html = ""
@@ -405,7 +433,7 @@ def render_commands_tab(commands: list[dict]) -> str:
                                     <span class="category-badge">{category}</span>
                                 </div>
                                 <div class="command-meta">
-                                    <span class="frequency">Used {frequency}x</span>
+                                    <span class="cmd-preview">{description[:60]}{'...' if len(description) > 60 else ''}</span>
                                     <span class="expand-icon">&#9660;</span>
                                 </div>
                             </div>
@@ -418,7 +446,9 @@ def render_commands_tab(commands: list[dict]) -> str:
                                     <h5>Description:</h5>
                                     <p>{description}</p>
                                 </div>
+                                {subcmd_html}
                                 {flags_html}
+                                {patterns_html}
                                 {output_html}
                             </div>
                         </div>'''
@@ -512,13 +542,37 @@ def render_lessons_tab(categories: dict, commands: list[dict]) -> str:
             complexity = cmd.get("complexity", "simple")
             highlighted = _syntax_highlight(cmd.get("full_command", ""))
 
+            # Get flags and patterns for this command from COMMAND_DB
+            cmd_flags = cmd.get("flags", [])
+            lesson_flags_html = ""
+            if cmd_flags:
+                lesson_flags_html = '<div class="lesson-flags"><strong>Flags used:</strong> '
+                flag_parts = []
+                for flag in cmd_flags:
+                    fname = html.escape(flag.get("flag", "") if isinstance(flag, dict) else str(flag))
+                    fdesc = html.escape(flag.get("description", "") if isinstance(flag, dict) else "")
+                    if fdesc:
+                        flag_parts.append(f'<code class="flag">{fname}</code> ({fdesc})')
+                    else:
+                        flag_parts.append(f'<code class="flag">{fname}</code>')
+                lesson_flags_html += ', '.join(flag_parts) + '</div>'
+
+            # Subcommand info
+            subcmd_desc = cmd.get("subcommand_desc", "")
+            lesson_subcmd = ""
+            if subcmd_desc:
+                lesson_subcmd = f'<div class="lesson-subcmd"><em>{html.escape(subcmd_desc)}</em></div>'
+
             cat_commands_html += f'''
                             <div class="lesson-command">
                                 <div class="lesson-command-header">
                                     <code class="cmd">{base_cmd}</code>
+                                    <span class="lesson-complexity complexity-{complexity}">{complexity}</span>
                                 </div>
                                 <pre class="syntax-highlighted">{highlighted}</pre>
                                 <p class="lesson-description">{description}</p>
+                                {lesson_subcmd}
+                                {lesson_flags_html}
                             </div>'''
 
         # Patterns observed
@@ -1304,9 +1358,13 @@ def get_inline_css() -> str:
             gap: 16px;
         }
 
-        .frequency {
-            font-size: 0.85rem;
+        .cmd-preview {
+            font-size: 0.8rem;
             color: var(--text-secondary);
+            max-width: 400px;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
         }
 
         .expand-icon {
@@ -1384,6 +1442,22 @@ def get_inline_css() -> str:
             color: #34a853;
         }
 
+        .flag-desc { color: #6c757d; margin-left: 4px; }
+        .flags-list li { margin: 4px 0; line-height: 1.5; }
+        .subcmd-section { background: #f0f7ff; padding: 8px 12px; border-radius: 6px; margin: 8px 0; border-left: 3px solid #4a9eff; }
+        .subcmd-label { font-weight: 600; color: #4a9eff; }
+        .patterns-section { margin: 8px 0; }
+        .patterns-section h5 { margin: 4px 0; color: #666; font-size: 0.85em; }
+        .patterns-list { list-style: none; padding: 0; margin: 4px 0; }
+        .patterns-list li { padding: 3px 0; }
+        .patterns-list code { background: #f5f5f5; padding: 2px 6px; border-radius: 3px; font-size: 0.85em; }
+        .lesson-flags { margin: 6px 0; font-size: 0.9em; color: #555; }
+        .lesson-subcmd { font-size: 0.9em; color: #4a9eff; margin: 4px 0; }
+        .lesson-complexity { font-size: 0.75em; padding: 2px 8px; border-radius: 10px; margin-left: 8px; }
+        .complexity-simple { background: #e8f5e9; color: #2e7d32; }
+        .complexity-intermediate { background: #fff3e0; color: #e65100; }
+        .complexity-advanced { background: #fce4ec; color: #c62828; }
+
         .syntax-highlighted .string {
             color: #ff6d01;
         }
@@ -2107,27 +2181,122 @@ def generate_html_files(
     # Transform commands to expected format
     formatted_commands = []
     for cmd in analyzed_commands:
-        # Convert flags to expected format (list of dicts with 'flag' and 'description')
+        cmd_str = cmd.get('command', '')
+        base_cmd = cmd.get('base_command', cmd_str.split()[0] if cmd_str else '')
+        complexity_score = cmd.get('complexity', 1)
+
+        # Look up COMMAND_DB info for this command
+        cmd_info = COMMAND_DB.get(base_cmd, {})
+        kb_flags = get_flags_for_command(base_cmd)
+
+        # Convert flags to expected format WITH descriptions from knowledge base
+        # Filter out non-flag tokens: bare dashes, numeric args (-5, -30), trailing colons
+        import re
         raw_flags = cmd.get('flags', [])
         formatted_flags = []
+        seen_flags = set()
         for f in raw_flags:
-            if isinstance(f, dict):
-                formatted_flags.append(f)
+            flag_name = f.get('flag', '') if isinstance(f, dict) else f
+            # Skip bare dash, numeric-only flags (-5, -30), and artifact flags with colons
+            if not flag_name or flag_name == '-' or flag_name.endswith(':'):
+                continue
+            if re.match(r'^-\d+$', flag_name):
+                continue
+            # Deduplicate flags within same command
+            if flag_name in seen_flags:
+                continue
+            seen_flags.add(flag_name)
+
+            if isinstance(f, dict) and 'flag' in f:
+                flag_desc = f.get('description', '')
+                if not flag_desc and flag_name in kb_flags:
+                    flag_desc = kb_flags[flag_name]
+                formatted_flags.append({'flag': flag_name, 'description': flag_desc})
             elif isinstance(f, str):
-                formatted_flags.append({'flag': f, 'description': ''})
-
-        cmd_str = cmd.get('command', '')
-        complexity_score = cmd.get('complexity', 1)
+                flag_desc = kb_flags.get(f, '')
+                # For combined flags like -la, decompose into individual flags
+                if not flag_desc and len(f) > 2 and f.startswith('-') and not f.startswith('--'):
+                    char_descs = []
+                    for char in f[1:]:
+                        single = f'-{char}'
+                        if single in kb_flags:
+                            char_descs.append(f'{single}: {kb_flags[single]}')
+                    if char_descs:
+                        flag_desc = '; '.join(char_descs)
+                # For find-style flags (-name, -type, -path, -maxdepth), add descriptions
+                if not flag_desc:
+                    find_flags = {
+                        '-name': 'Match files by name pattern',
+                        '-type': 'Filter by file type (f=file, d=directory)',
+                        '-path': 'Match files by path pattern',
+                        '-maxdepth': 'Limit directory recursion depth',
+                        '-mindepth': 'Set minimum directory depth',
+                        '-exec': 'Execute command on each match',
+                        '-not': 'Negate the following expression',
+                        '-size': 'Match files by size',
+                        '-mtime': 'Match by modification time',
+                        '-perm': 'Match by file permissions',
+                        '-ls': 'List matched files in ls -l format',
+                        '-delete': 'Delete matched files',
+                        '-print': 'Print matched file paths',
+                    }
+                    flag_desc = find_flags.get(f, '')
+                # For common CLI flags without KB entries
+                if not flag_desc:
+                    common_flags = {
+                        '--help': 'Show help and usage information',
+                        '--version': 'Show version number',
+                        '--verbose': 'Enable verbose output',
+                        '--dry-run': 'Preview changes without executing',
+                        '--output': 'Specify output file or directory',
+                        '--open': 'Open result in default application',
+                        '--stat': 'Show diffstat summary of changes',
+                        '--sessions': 'Number of sessions to process',
+                        '--title': 'Set custom title',
+                        '--no-open': 'Skip auto-opening in browser',
+                        '--from': 'Specify input source path',
+                        '-s': 'Silent/short output mode',
+                        '-n': 'Numeric/count or line number',
+                        '-c': 'Execute command string or count',
+                        '-g': 'Global scope',
+                        '-p': 'Preserve attributes or port',
+                        '-o': 'Output file',
+                        '-P': 'No dereference (physical path)',
+                    }
+                    flag_desc = common_flags.get(f, '')
+                formatted_flags.append({'flag': f, 'description': flag_desc})
+
+        # Get educational description from COMMAND_DB if session description is empty/generic
+        session_desc = cmd.get('description', '')
+        kb_desc = cmd_info.get('description', '')
+        description = session_desc if session_desc else kb_desc
+
+        # Get subcommand info (for commands like git, docker, npm)
+        subcommands = cmd_info.get('subcommands', {})
+        # Try to identify the subcommand from the full command
+        cmd_tokens = cmd_str.split() if cmd_str else []
+        subcommand_desc = ''
+        if subcommands and len(cmd_tokens) > 1:
+            for token in cmd_tokens[1:]:
+                if not token.startswith('-') and token in subcommands:
+                    subcommand_desc = subcommands[token]
+                    break
+
+        # Get common patterns from COMMAND_DB
+        common_patterns = cmd_info.get('common_patterns', [])
 
         formatted_commands.append({
-            'base_command': cmd.get('base_command', cmd_str.split()[0] if cmd_str else ''),
+            'base_command': base_cmd,
             'full_command': cmd_str,
             'category': cmd.get('category', 'Other'),
             'complexity': complexity_to_label(complexity_score),
             'complexity_score': complexity_score,
             'frequency': frequency_map.get(cmd_str, 1),
-            'description': cmd.get('description', ''),
+            'description': description,
             'flags': formatted_flags,
+            'subcommand_desc': subcommand_desc,
+            'common_patterns': common_patterns[:6],
+            'args': cmd.get('args', []),
             'is_new': False,
         })