Git Commit Video Walkthrough Generator

A command-line tool that generates narrated video walkthroughs of git commits, staged/unstaged changes, or entire codebases with AI-powered analysis and explanations.

Features

• 🎥 Automatic video generation from git commits, diffs, or codebases

• 🤖 AI-powered code analysis using Claude (Anthropic) or Gemini (Google)

• 🗣️ Natural text-to-speech narration

• 🎨 Syntax-highlighted code visualization

• 📊 Multiple presentation styles (beginner, technical, overview)

• ⚡ Standalone CLI - no external services required

• 🔑 Direct LLM API integration (Anthropic, Google AI)

Installation

Prerequisites

• FFmpeg: Required for video compilation

  • macOS: brew install ffmpeg

  • Linux: apt install ffmpeg

  • Windows: Download from ffmpeg.org

• Node.js/Bun: For running the CLI

  • Recommended: Bun 1.0+ (curl -fsSL https://bun.sh/install | bash)

  • Or Node.js 20+

• LLM API Key: You need an API key from one of these providers:

  • Anthropic Claude: Get from console.anthropic.com

  • Google AI: Get from ai.google.dev

Install from Source

# Clone the repository
git clone https://github.com/yourusername/code-walkthrough-cli.git
cd code-walkthrough-cli

# Install dependencies
bun install

# Build TypeScript
bun run build

# Optional: Create compiled binary
bun run build:bin

Setup API Keys

Set your API key as an environment variable:

# For Anthropic Claude
export ANTHROPIC_API_KEY="your-api-key-here"

# Or for Google Gemini
export GOOGLE_API_KEY="your-api-key-here"

# Add to your shell profile (~/.zshrc, ~/.bashrc) to persist
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc

Usage

Basic Usage

# Analyze a specific commit
git-commit-video abc123

# Analyze staged changes
git-commit-video --staged

# Analyze unstaged changes
git-commit-video --unstaged

# Analyze entire codebase
git-commit-video --codebase

Options

git-commit-video <commit-hash> [options]

Options:
  --repo <path>          Path to git repository (default: current directory)
  --output <path>        Output video path (default: ./walkthrough.mp4)
  --style <style>        Presentation style: beginner, technical, overview (default: technical)
  --theme <theme>        Visual theme: dark, light, github (default: dark)
  --llm <provider>       LLM provider: anthropic, google (default: anthropic)
  --model <name>         Specific model to use (default: provider's latest)
  --help, -h             Show help

Examples

# Generate video for commit with technical style
git-commit-video abc123 --style technical

# Analyze staged changes with light theme
git-commit-video --staged --theme light --output ./staged-changes.mp4

# Analyze entire codebase using Google Gemini
git-commit-video --codebase --llm google --style overview

# Use specific repository path
git-commit-video abc123 --repo /path/to/repo --output ./my-video.mp4

Target Types

• Specific Commit: git-commit-video <commit-hash>

• Staged Changes: git-commit-video --staged

• Unstaged Changes: git-commit-video --unstaged

• Entire Codebase: git-commit-video --codebase

Presentation Styles

• beginner: Detailed explanations, slower pace, educational tone

• technical: Precise, focused on implementation details

• overview: Quick, high-level summary of changes

Visual Themes

• dark: Dark background (ideal for code)

• light: Light background

• github: GitHub-style syntax highlighting

How It Works

The CLI follows a three-stage pipeline:

1. Extract Git Data: Analyzes commits, diffs, or codebase structure

2. LLM Analysis: Calls Claude/Gemini API to analyze code and generate narration script

3. Video Generation: Creates frames, generates audio, compiles into MP4

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Git Data   │ --> │ LLM Analysis │ --> │ Video Gen   │
│  Extraction │     │  (API Call)  │     │ (Frames+TTS)│
└─────────────┘     └──────────────┘     └─────────────┘

Configuration

API Key Configuration

You can provide your API key in multiple ways (in order of precedence):

1. Environment Variable (recommended):

   export ANTHROPIC_API_KEY="your-key"
   # or
   export GOOGLE_API_KEY="your-key"

2. Command-line Argument:

   git-commit-video abc123 --api-key "your-key"

3. Config File (~/.git-commit-video/config.json):

   {
     "anthropicApiKey": "your-key",
     "googleApiKey": "your-key",
     "defaultLlm": "anthropic",
     "defaultStyle": "technical",
     "defaultTheme": "dark"
   }

LLM Providers

Anthropic Claude (default):

• Best for code analysis

• Models: claude-3-5-sonnet-20241022, claude-3-opus-20240229

• Get API key: console.anthropic.com

Google Gemini:

• Fast and cost-effective

• Models: gemini-1.5-pro, gemini-1.5-flash

• Get API key: ai.google.dev

Project Structure

.
├── src/
│   ├── cli.ts                # CLI entry point
│   ├── index.ts              # Core application logic
│   ├── stages/
│   │   ├── analysis.ts       # LLM analysis via API
│   │   ├── script.ts         # Script generation via API
│   │   └── video.ts          # Video generation pipeline
│   ├── extractors/
│   │   ├── commit.ts         # Extract commit info
│   │   ├── staged.ts         # Extract staged changes
│   │   ├── unstaged.ts       # Extract unstaged changes
│   │   └── codebase.ts       # Extract codebase info
│   ├── llm/
│   │   ├── anthropic.ts      # Anthropic API integration
│   │   ├── google.ts         # Google AI integration
│   │   └── types.ts          # LLM provider interface
│   ├── types/
│   │   ├── state.ts          # Type definitions
│   │   └── analysis.ts       # Analysis types
│   └── utils/
│       ├── prompts.ts        # LLM prompts for analysis
│       └── args.ts           # CLI argument parsing
├── dist/                     # Compiled JavaScript
├── bin/
│   └── git-commit-video      # Compiled binary (optional)
└── video_output/             # Generated videos (default)

Development

# Watch mode (auto-rebuild on changes)
bun run watch

# Run CLI locally
bun run dev

# Build TypeScript
bun run build

# Build standalone binary
bun run build:bin

# Run tests
bun test

Architecture

This CLI application uses a straightforward pipeline:

1. User runs CLI command with target (commit, staged, unstaged, codebase)

2. CLI extracts code/commits from git repository

3. CLI calls LLM API (Anthropic/Google) to analyze code

4. LLM returns structured analysis (JSON)

5. CLI calls LLM API again to generate narration script

6. LLM returns timed script with narration

7. CLI generates video frames, audio, and compiles final MP4

All processing happens locally - only the LLM analysis is done via API calls.

Video Generation Pipeline

1. Analysis: Code is analyzed to understand what it does

2. Script: A narrated script is generated based on analysis

3. Frames: HTML frames are created with syntax-highlighted code

4. Screenshots: Puppeteer captures PNG screenshots of each frame

5. Audio: Text-to-speech generates narration audio

6. Compilation: FFmpeg combines frames and audio into MP4

Output

The generated video includes:

• Introduction with project overview

• Section-by-section code walkthrough

• Syntax-highlighted code snippets

• Professional narration

• Conclusion summary

Example output structure:

walkthrough.mp4           # Final video
temp_frames/              # Temporary frame images (auto-deleted)
temp_audio.mp3           # Temporary audio (auto-deleted)

Troubleshooting

"API Key Not Found" Error

Make sure you've set your API key:

export ANTHROPIC_API_KEY="your-key"
# or
export GOOGLE_API_KEY="your-key"

Add it to your shell profile to persist across sessions.

"FFmpeg Not Found" Error

Install FFmpeg:

• macOS: brew install ffmpeg

• Linux: apt install ffmpeg

• Windows: Download from ffmpeg.org and add to PATH

Verify installation: ffmpeg -version

"Invalid JSON Response" Error

The LLM returned malformed JSON. This can happen with very large diffs. Try:

• Analyzing a smaller commit

• Using a different LLM provider (--llm google)

• Using a more capable model (--model claude-3-opus-20240229)

No Audio in Video

The CLI uses system text-to-speech. If TTS fails, the video will be generated without audio (silent).

To improve TTS quality, install edge-tts:

pip install edge-tts

Puppeteer Issues

Puppeteer downloads Chromium automatically. If it fails:

# Reinstall dependencies
rm -rf node_modules
bun install

Rate Limiting

If you hit API rate limits, the CLI will automatically retry with exponential backoff. For large codebases, consider:

• Using --style overview for shorter analysis

• Splitting analysis into multiple commits

• Using a higher rate limit tier with your LLM provider

Cost Estimates

Typical API costs (approximate):

Use --dry-run to see estimated costs before execution.

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript code compiles without errors

• Follow existing code style

• Update documentation for new features

• Add tests for new functionality

Roadmap

• Support for more LLM providers (OpenAI, Cohere)

• Custom TTS voices

• Interactive mode with live preview

• Video editing features (trim, merge sections)

• Export to different formats (GIF, WebM)

• GitHub Actions integration