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

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

@@ -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">{description[:60]}{'...' if len(description) > 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 {
@@ -2186,20 +2190,31 @@ def generate_html_files(
         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,6 +2223,47 @@ 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