learn_bash_from_session_data 1.0.7 → 1.0.9

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learn_bash_from_session_data",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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

@@ -433,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">{' '.join(description.split())[:60]}{'...' if len(' '.join(description.split())) > 60 else ''}</span>
                                     <span class="expand-icon">&#9660;</span>
                                 </div>
                             </div>
@@ -1358,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 {
@@ -2181,25 +2185,54 @@ def generate_html_files(
         base_cmd = cmd.get('base_command', cmd_str.split()[0] if cmd_str else '')
         complexity_score = cmd.get('complexity', 1)
 
+        # Filter out non-bash entries (Python/JS code fragments, single chars, status text)
+        if not base_cmd or len(base_cmd) < 2:
+            continue
+        # Skip entries that look like code fragments (contain parens, equals, dots as methods)
+        if any(c in base_cmd for c in ('(', ')', '=', '{', '}')) and not base_cmd.startswith('.'):
+            continue
+        # Skip entries that are clearly not commands (capitalized status words, text fragments)
+        if base_cmd[0].isupper() and base_cmd.isalpha() and base_cmd not in ('PATH', 'HOME'):
+            continue
+        # Skip common text fragments that get misidentified as commands
+        junk_tokens = {'version', 'total', 'package', 'success', 'error', 'reading',
+                       'editing', 'done', 'warning', 'info', 'note', 'output'}
+        if base_cmd.lower() in junk_tokens:
+            continue
+
+        # Tokenize the command for subcommand/description generation
+        cmd_tokens = cmd_str.split() if cmd_str else []
+
         # 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:
+            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:
-                # Already formatted - but enrich description if empty
-                flag_name = f.get('flag', '')
                 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):
-                # Raw flag string - look up description from knowledge base
                 flag_desc = kb_flags.get(f, '')
-                # For combined flags like -la, try individual characters
+                # 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:]:
@@ -2208,17 +2241,117 @@ def generate_html_files(
                             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
+        # Generate a contextual description that differentiates commands with the same base
         session_desc = cmd.get('description', '')
         kb_desc = cmd_info.get('description', '')
-        description = session_desc if session_desc else kb_desc
+
+        # Build a specific description from the actual command content
+        args_list = cmd.get('args', [])
+        flag_list = [fl.get('flag', '') if isinstance(fl, dict) else str(fl) for fl in formatted_flags]
+        contextual_desc = ''
+
+        # For inline code execution (python -c, bash -c), summarize the code snippet
+        if base_cmd in ('python', 'python3', 'bash', 'sh', 'node') and '-c' in flag_list:
+            # Extract the inline code from the full command after -c
+            c_idx = cmd_str.find('-c')
+            if c_idx >= 0:
+                raw_code = cmd_str[c_idx + 2:].strip().strip('"').strip("'")
+                # Split on actual newlines before collapsing
+                code_lines = [l.strip() for l in raw_code.splitlines() if l.strip()]
+                # Find first non-import line for a distinctive preview
+                action_lines = [l for l in code_lines if not l.startswith(('import ', 'from ', '#'))]
+                if action_lines:
+                    code_part = ' '.join(action_lines[0].split())[:60]
+                elif code_lines:
+                    # All imports - show what's being imported
+                    code_part = ' '.join(code_lines[0].split())[:60]
+                else:
+                    code_part = ''
+                if code_part:
+                    contextual_desc = f"{base_cmd} -c: {code_part}{'...' if len(code_part) >= 60 else ''}"
+
+        # For commands with subcommands (git, npm, docker, etc.), use subcommand context
+        if not contextual_desc and cmd_tokens and len(cmd_tokens) > 1:
+            subcmd_token = next((t for t in cmd_tokens[1:] if not t.startswith('-') and not t.startswith('"') and not t.startswith("'")), '')
+            if subcmd_token and subcmd_token != base_cmd:
+                subcmd_info = cmd_info.get('subcommands', {}).get(subcmd_token, '')
+                if subcmd_info:
+                    contextual_desc = f"{base_cmd} {subcmd_token}: {subcmd_info}"
+                else:
+                    contextual_desc = f"{base_cmd} {subcmd_token}"
+                # Add meaningful args (skip very long ones, quotes, code)
+                short_args = [a for a in args_list if len(str(a)) < 40 and a != subcmd_token and not a.startswith('"')]
+                if short_args:
+                    contextual_desc += f" ({', '.join(short_args[:3])})"
+
+        # For commands with flags but no subcommand, describe with flags
+        if not contextual_desc and flag_list:
+            flag_summary = ', '.join(flag_list[:3])
+            short_args = [a for a in args_list if len(str(a)) < 40]
+            if short_args:
+                contextual_desc = f"{base_cmd} {flag_summary} on {', '.join(short_args[:2])}"
+            else:
+                contextual_desc = f"{base_cmd} with {flag_summary}"
+
+        # For simple commands with just args
+        if not contextual_desc and args_list:
+            short_args = [a for a in args_list if len(str(a)) < 40]
+            if short_args:
+                contextual_desc = f"{base_cmd} {' '.join(short_args[:3])}"
+
+        # Priority: contextual > session > knowledge base
+        if contextual_desc:
+            description = contextual_desc
+        elif session_desc:
+            description = session_desc
+        else:
+            description = kb_desc if kb_desc else f"Run {base_cmd} command"
 
         # 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:]:

package/scripts/knowledge_base.py

@@ -91,6 +91,8 @@ CATEGORY_MAPPINGS: Dict[str, Set[str]] = {
         "history", "fc", "true", "false", "test", "[", "[[", "exit",
         "return", "break", "continue", "shift", "getopts", "trap",
         "ulimit", "times", "let", ":", "compgen", "complete", "compopt",
+        "cmd.exe", "cmd", "start", "where", "type",
+        "session-slides", "learn-bash", "bash-learner", "claude",
     },
 }