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
- macOS:
-
Node.js/Bun: For running the CLI
- Recommended: Bun 1.0+ (
curl -fsSL https://bun.sh/install | bash) - Or Node.js 20+
- Recommended: Bun 1.0+ (
-
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:
- Extract Git Data: Analyzes commits, diffs, or codebase structure
- LLM Analysis: Calls Claude/Gemini API to analyze code and generate narration script
- 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):
-
Environment Variable (recommended):
export ANTHROPIC_API_KEY="your-key" # or export GOOGLE_API_KEY="your-key" -
Command-line Argument:
git-commit-video abc123 --api-key "your-key" -
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:
- User runs CLI command with target (commit, staged, unstaged, codebase)
- CLI extracts code/commits from git repository
- CLI calls LLM API (Anthropic/Google) to analyze code
- LLM returns structured analysis (JSON)
- CLI calls LLM API again to generate narration script
- LLM returns timed script with narration
- 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
- Analysis: Code is analyzed to understand what it does
- Script: A narrated script is generated based on analysis
- Frames: HTML frames are created with syntax-highlighted code
- Screenshots: Puppeteer captures PNG screenshots of each frame
- Audio: Text-to-speech generates narration audio
- 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 overviewfor shorter analysis - Splitting analysis into multiple commits
- Using a higher rate limit tier with your LLM provider
Cost Estimates
Typical API costs (approximate):
| Target Type | Tokens | Anthropic (Claude) | Google (Gemini) |
|---|---|---|---|
| Small commit (~10 files) | ~3K | $0.01 | $0.00 |
| Medium commit (~50 files) | ~15K | $0.05 | $0.01 |
| Large commit (~200 files) | ~60K | $0.20 | $0.03 |
| Entire codebase (small) | ~20K | $0.07 | $0.01 |
| Entire codebase (large) | ~100K | $0.35 | $0.05 |
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