Git Time Machine Lite 🕰️

AI-powered git history analyzer that identifies risky commits and explains how bugs were introduced

Overview

Git Time Machine Lite is a powerful CLI tool that analyzes your git repository history to automatically detect risky code changes that could introduce bugs. It uses sophisticated heuristics to score commits based on removed safety checks, error handling, and other risk factors, then leverages AI to explain how these changes might cause issues.

Features

✅ Auto-detection of risky files - Scans git history to find the most dangerous changes
✅ Multiple LLM providers - Support for OpenAI, Gemini, Claude, and Grok
✅ Smart commit analysis - Detects removed error handling, conditionals, and safety checks
✅ Interactive CLI - User-friendly prompts for easy configuration
✅ Zero dependencies on external services - Works offline (without AI) for basic analysis
✅ Fast & efficient - Optimized for large repositories

Installation

Global Installation (Recommended)

npm install -g git-time-machine-lite

Local Installation

npm install git-time-machine-lite
npx git-time-machine-lite

From Source

git clone https://github.com/THRISHAL12345/git-time-machine-lite.git
cd git-time-machine-lite
npm install
npm link

Quick Start

1. Navigate to your git repository:

   cd /path/to/your/project

2. Run the tool:

   git-time-machine-lite --auto
   # or use the shorter alias
   gtm --auto

3. Analyze a specific file:

   git-time-machine-lite src/index.js

Usage

Commands

# Auto-detect risky files (recommended)
git-time-machine-lite --auto

# Analyze a specific file
git-time-machine-lite path/to/file.js

# Configure LLM provider
git-time-machine-lite config

# Check system status
git-time-machine-lite doctor

# Show help
git-time-machine-lite --help

# Interactive mode (no arguments)
git-time-machine-lite

Configuration

Before using AI features, configure your preferred LLM provider:

git-time-machine-lite config

Then set your API key as an environment variable:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Gemini (Google)
export GEMINI_API_KEY="your-api-key"

# Claude (Anthropic)
export CLAUDE_API_KEY="your-api-key"

# Grok (xAI)
export GROK_API_KEY="your-api-key"

Windows (PowerShell):

$env:OPENAI_API_KEY="your-api-key"

Windows (CMD):

set OPENAI_API_KEY=your-api-key

How It Works

1. Git History Scan: Analyzes recent commits to find changed files
2. Risk Analysis: Scores commits based on:
   • Removed conditional checks (if/else/switch)
   • Removed error handling (try/catch)
   • Removed validation (throw/assert)
   • Removed null-safety operators
   • Async/await modifications
   • Deletion-heavy refactors
   • Loop logic changes
3. AI Explanation: Sends risky commits to your chosen LLM for detailed analysis
4. Report: Displays findings with risk scores and AI insights

Risk Detection Heuristics

The tool uses the following heuristics to detect potentially risky commits:

| Risk Factor | Score | Description | |------------|-------|-------------| | Removed conditionals | 3 | Deleted if/else/switch statements | | Removed try/catch | 3 | Deleted error handling blocks | | Removed validation | 2 | Deleted throw/assert statements | | Removed null-safety | 2 | Deleted optional chaining or fallbacks | | Deletion-heavy refactor | 2 | More deletions than additions | | Async/await changes | 2 | Modified async code patterns | | Loop changes | 1 | Modified for/while/forEach logic | | Error handling reduction | 2 | Reduced error checking code |

Maximum Risk Score: 10/10

Supported File Types

The tool analyzes the following programming languages:

• JavaScript/TypeScript: .js, .jsx, .ts, .tsx
• Java/Kotlin: .java, .kt
• Go: .go
• Python: .py
• Ruby: .rb
• PHP: .php
• C/C++: .c, .cpp, .cc, .h
• Rust: .rs
• Swift: .swift
• C#: .cs

Configuration File

The tool stores settings in ~/.git-time-machine/config.json:

{
  "llmProvider": "openai"
}

Examples

Example 1: Auto-detection

$ git-time-machine-lite --auto

🔍 Scanning git history for risky changes...

📄 src/auth.js - Risk Score: 8/10
📄 src/database.js - Risk Score: 6/10
📄 src/api/users.js - Risk Score: 5/10

✅ Scanned 23 files

🧠 AI Explanation:

This commit removed critical error handling in the authentication flow...

Example 2: Specific file analysis

$ git-time-machine-lite src/payment.js

🧠 AI Explanation:

The removed try/catch block in the payment processing function could lead to 
unhandled exceptions when the payment gateway returns an error...

Troubleshooting

"Not a git repository"

Make sure you're running the command inside a git repository:

git status  # Should not show an error

"No risky files detected"

This means your recent commits don't trigger the risk heuristics. Try:

• Analyzing a specific file that you know has issues
• Checking older commits (the tool scans the last 50 commits by default)

API Key Issues

Run the doctor command to verify your setup:

git-time-machine-lite doctor

AI Provider Not Responding

• Check your internet connection
• Verify your API key is correct
• Check API provider status pages
• The tool has a 15-second timeout for API requests

Performance Tips

1. Use auto-detection instead of scanning all files
2. Limit scope by analyzing specific files when possible
3. Run locally for large repositories to avoid API costs
4. The tool automatically:
   • Caches file lists
   • Truncates large diffs
   • Filters test files and documentation

Privacy & Security

• No data collection: The tool doesn't send any telemetry
• Local processing: Git analysis happens entirely on your machine
• API calls: Only risky commit diffs are sent to your chosen AI provider
• API keys: Stored as environment variables, never in code
• No logging: API keys and responses are not logged to disk

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development

# Clone the repository
git clone https://github.com/THRISHAL12345/git-time-machine-lite.git
cd git-time-machine-lite

# Install dependencies
npm install

# Link for local development
npm link

# Test your changes
git-time-machine-lite --auto

Roadmap

• [ ] Add support for more LLM providers (Llama, Mistral, etc.)
• [ ] Implement caching for AI responses
• [ ] Add JSON/HTML report output
• [ ] Support for custom risk heuristics
• [ ] Integration with CI/CD pipelines
• [ ] VSCode extension
• [ ] Unit tests and integration tests
• [ ] Performance benchmarks

License

MIT License - see LICENSE file for details

Credits

Created by THRISHAL12345

Support

• 🐛 Report Issues
• 💬 Discussions
• ⭐ Star on GitHub

Note: This tool provides suggestions based on heuristics and AI analysis. Always use your judgment when evaluating code risks.