ExplainWatch - MVP1

A code change timeline generator that captures semantic history of a repository and renders documentary-style videos with accurate, per-change explanations.

Features (MVP1)

• File Watching: Captures file changes with unified diffs
• Symbol Indexing: Tree-sitter based symbol extraction for TypeScript and Python
• Change Classification: Automatic categorization (feature, bugfix, refactor, config, etc.)
• Noise Collapsing: Groups related changes, collapses formatting-only edits
• Grounded Narration: Explanations tied to actual code changes with evidence
• Video Rendering: HTML→PNG frames stitched with ffmpeg
• Risk Detection: Flags potential security issues (hardcoded secrets, unsafe patterns)

Installation

npm install
npm run build

Prerequisites

• Node.js 18+
• ffmpeg (for video generation)
• Playwright browsers (auto-installed)

# Install ffmpeg (Windows)
winget install ffmpeg

# Or with Chocolatey
choco install ffmpeg

# Install Playwright browsers
npx playwright install chromium

Usage

Start Recording

# Watch current directory
npx explainwatch start

# Watch specific repository
npx explainwatch start --path /path/to/repo

# With custom output directory
npx explainwatch start --output ./output

# Choose narration style
npx explainwatch start --style diff-first  # minimal commentary
npx explainwatch start --style narrated    # default, with explanations
npx explainwatch start --style lecture     # includes concept explanations

Press Ctrl+C to stop recording. The tool will automatically generate:

• timeline.json - Structured event timeline
• summary.md - Human-readable summary
• video.mp4 - Documentary-style video
• captions.srt - Subtitles

List Sessions

npx explainwatch list

Generate from Existing Session

npx explainwatch generate --session <session-id>

Execute Commands (Captures Output)

npx explainwatch exec npm test
npx explainwatch exec cargo build

Architecture

src/
├── types/          # Event and segment schemas (Zod)
├── capture/        # File watcher, command capture
├── analysis/       # Symbol indexer, change classifier, segmenter
├── narration/      # Script generator
├── render/         # HTML templates, video renderer
├── storage/        # Event store (JSONL + patches)
├── core/           # Session manager
└── cli.ts          # CLI entry point

Event Types

• FileChanged - File modifications with unified diff
• CommandExecuted - Terminal command with stdout/stderr
• SymbolGraphChanged - Added/removed/modified symbols
• DependencyChanged - Package manager changes

Output Formats

timeline.json

{
  "version": 1,
  "sessionId": "uuid",
  "chapters": [
    {
      "title": "Authentication",
      "segments": [
        {
          "title": "Added AuthMiddleware",
          "changeType": "feature",
          "narration": "At 03:12, new functionality was added...",
          "evidence": [{"claim": "...", "file": "...", "lineRange": [1, 10]}],
          "impactedSymbols": [{"name": "AuthMiddleware", "kind": "class"}]
        }
      ]
    }
  ]
}

summary.md

Human-readable markdown with chapters, segments, and risk flags.

Narration Styles

| Style | Description | |-------|-------------| | diff-first | Minimal - shows diffs with brief commentary | | narrated | Default - includes "what changed" and "why" explanations | | lecture | Educational - pauses to explain concepts (middleware, DI, etc.) |

Ignored Patterns

By default, these are ignored:

• node_modules/, .git/, dist/, build/
• .next/, __pycache__/, .venv/
• Lock files (package-lock.json, yarn.lock, etc.)

Add custom patterns:

npx explainwatch start --ignore "*.log" --ignore "coverage/"

Limitations (MVP1)

• Symbol indexing only for TypeScript and Python
• No TTS audio (video has subtitles only)
• No IDE integration (repo-only mode)
• Requires ffmpeg for video output

Roadmap to MVP2

• [ ] VSCode extension for agent message capture
• [ ] TTS audio narration
• [ ] Go/Rust symbol indexing
• [ ] "Ask follow-up" feature
• [ ] Multiple zoom levels (5min/30min/3hr summaries)

License

MIT