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

Setup API Keys

Set your API key as an environment variable:

Usage

Basic Usage

Options

Examples

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

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

Development

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:

Troubleshooting

"API Key Not Found" Error

Make sure you've set your API 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:

Puppeteer Issues

Puppeteer downloads Chromium automatically. If it fails:

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