git-timeline

v3.0.0

Published

2 months ago

MCP server with agent-based AI analysis. Generates beautiful visual timelines by analyzing git history. Track features and tooling evolution with superior quality - the agent analyzes using its own authentication (no API key needed).

Git Timeline MCP Server 🚀

A Model Context Protocol (MCP) server that analyzes your project's git history and generates beautiful, interactive visual timelines. Track your project's evolution by visualizing feature development and tooling adoption over time.

New in v3.0: 🤖 Agent-Based AI Analysis - No API key needed! The AI agent (Claude/Copilot) analyzes data using its own authentication.

Features

🎯 Three Analysis Modes

📅 Fast Mode (Pattern-Based)

Instant analysis using file patterns and heuristics:

Analyzes source file modifications to identify feature additions
Detects domains from file paths, function names, and code patterns
Groups features by date with intelligent categorization
Shows actual file names as tags (controllers, services, pages, etc.)
Instant results - no API calls needed

🤖 Smart Mode (Agent-Based AI)

Superior quality with semantic understanding:

Gathers commit data (diffs, file contents, metadata)
Returns to AI agent for analysis using its existing authentication
No API key setup required - works with Claude, Copilot, or any AI agent
Transparent analysis - you see and control the entire process
Context-aware descriptions that explain what was built and why it matters
Groups by business capability rather than technical patterns

🔧 Tooling Timeline

Track technology stack evolution:

Monitors dependencies from package.json changes
Detects tooling from configuration files (eslint, prettier, docker, etc.)
Fetches package descriptions from npm registry for context
Shows only newly introduced tools (filters out version updates)

📊 Interactive Dashboard

Central hub for project insights:

Side-by-side comparison of features and tooling
Quick navigation between timelines
Responsive design for desktop and mobile
Beautiful gradient UI with card-based layout

Why Agent-Based Analysis?

The new v3.0 architecture is simpler and better:

✅ No Setup - No API keys, no environment variables, no configuration
✅ Works Everywhere - Compatible with Claude, GitHub Copilot, or any AI agent
✅ Transparent - You see the data and control the analysis
✅ Cost Effective - Uses your existing AI subscription
✅ Superior Quality - AI agents understand context better than automated calls

Prerequisites

Node.js >= 18.0.0
A git repository to analyze
VS Code with GitHub Copilot (for MCP integration)
For Smart Mode: Active AI agent (Claude/Copilot)

Installation

Option 1: Install from npm (Recommended)

Install globally to use the CLI command anywhere:

npm install -g @pramodyadav027/git-timeline

# Then use the CLI command in any git repository
cd /path/to/your/project
git-timeline

Or use without installing via npx:

npx @pramodyadav027/git-timeline

Option 2: Local Development/Testing

git clone <repo-url>
cd git-timeline
npm install
npm start

MCP Integration with VS Code + GitHub Copilot

Quick Setup

Open VS Code settings (Cmd+, on Mac, Ctrl+, on Windows)
Search for "mcp"
Click "Edit in settings.json" under "GitHub Copilot > MCP: Servers"
Add the Git Timeline server configuration:

{
  "github.copilot.chat.mcp.enabled": true,
  "github.copilot.chat.mcp.servers": {
    "git-timeline": {
      "command": "npx",
      "args": ["@pramodyadav027/git-timeline"]
    }
  }
}

Verify Installation

Open GitHub Copilot Chat in VS Code
Type @workspace and you should see the Git Timeline tools available

Usage

Using MCP Tools in VS Code Chat

The server provides 6 MCP tools accessible through GitHub Copilot Chat:

Fast Mode Tools (Instant Results)

Generate Feature Timeline:

@workspace Use the generateFeatureTimeline tool to analyze this repository

Generate Tooling Timeline:

@workspace Use the generateToolingTimeline tool to show tooling evolution

Generate All Timelines:

@workspace Use the generateAllTimelines tool to generate complete dashboard

Smart Mode Tools (Agent-Based AI)

Smart Feature Analysis:

@workspace Use the generateSmartFeatureTimeline tool to gather commit data for AI analysis

The tool will:

Gather commit data (file contents, diffs, metadata)
Return structured data with an analysis prompt
You analyze the data and respond with timeline events
Optionally generate HTML/Markdown files from your analysis

Smart Tooling Analysis:

@workspace Use the generateSmartToolingTimeline tool for enhanced tooling insights

Comprehensive Smart Analysis:

@workspace Use the generateSmartTimelines tool for complete AI-powered timeline

Using the CLI

Run directly in any git repository:

# Generate all timelines with dashboard (fast mode)
git-timeline

# Or specify max commits
git-timeline --max-commits 500

# Generate only feature timeline
git-timeline --features-only

# Generate only tooling timeline
git-timeline --tooling-only

Output Files

Generated files are saved in the .timeline/ directory of your repository:

Fast Mode:

{projectName}_feature_timeline.html - Interactive feature timeline
{projectName}_feature_timeline.md - Markdown version
{projectName}_tooling_timeline.html - Interactive tooling timeline
{projectName}_tooling_timeline.md - Markdown version
index.html - Main dashboard combining both timelines

Smart Mode (generated from your analysis):

Custom timelines based on your AI analysis
Can be exported to any format you prefer

How Smart Mode Works

The Agent-Based Flow

You request analysis:

@workspace Analyze my git history with smart mode

MCP tool gathers data:
- Scans git commits
- Extracts file changes and diffs
- Reads file contents
- Compiles metadata
Returns data + prompt:
- Structured commit data (JSON)
- Analysis instructions
- Best practices guidance
You analyze with AI:
- Review the data
- Use AI to identify patterns
- Generate business-focused descriptions
- Create timeline events
Optional file generation:
- Ask to generate HTML/Markdown from your analysis
- Create dashboard visualizations
- Export in any format

Example Workflow

You: @workspace Use generateSmartFeatureTimeline to analyze the last 50 commits

Agent: ✅ Gathered data for 50 commits

Here's the commit data with analysis prompt...

[Data + Prompt displayed]

You: [Review the data and respond with timeline JSON]

{
  "timeline": [
    {
      "date": "2024-01-15",
      "title": "User Authentication",
      "description": "Implemented secure login with JWT tokens",
      "category": "authentication",
      "icon": "🔐"
    },
    ...
  ]
}

Agent: Great! Want me to generate HTML/Markdown files from this timeline?

You: Yes, generate the HTML dashboard

Agent: ✅ Generated timeline dashboard at .timeline/custom_timeline.html

Advanced Configuration

Time-Based Aggregation Options

Smart mode supports three aggregation levels for grouping commits:

Day (default) - Best for active projects:

Groups commits by individual days
Shows detailed day-by-day velocity
Recommended for: 30-90 day lookback windows
Example: aggregation: 'day' with days: 90

Week - Good for longer timeframes:

Groups commits by week
Reduces data size while maintaining clarity
Recommended for: 90-180 day lookback windows
Example: aggregation: 'week' with days: 120

Month - Best for long-term view:

Groups commits by month
Provides high-level project evolution
Recommended for: 180+ day lookback windows or entire project history
Example: aggregation: 'month' with days: 365

# Use week aggregation for 6-month analysis
@workspace Use generateSmartFeatureTimeline with aggregation=week and days=180

# Use month aggregation for full project history
@workspace Use generateSmartFeatureTimeline with aggregation=month and days=730

Customizing Commit Scan Limits

Default is 100 commits for smart mode (to avoid token limits). Adjust as needed:

@workspace Use generateSmartFeatureTimeline with maxCommits=50

Excluding Files

The server automatically filters out:

Configuration files (package-lock.json, yarn.lock, etc.)
Build artifacts
Documentation (unless it's the main change)
Lock files

Custom Timeline Generation

You can ask the agent to:

Focus on specific features
Group by time period (weekly, monthly)
Highlight specific technologies
Create custom visualizations

Examples

Example 1: Quick Feature Overview

@workspace Generate a feature timeline for the last 100 commits

Example 2: Smart Analysis with Grouping

@workspace Use smart mode to analyze commits and group related changes by feature

Example 3: Tooling Evolution

@workspace Show me how our tech stack evolved over time

Example 4: Custom Date Range

@workspace Analyze commits from the last 6 months and create a timeline

Troubleshooting

Common Issues

Q: The smart tools return too much data
A: Reduce maxCommits parameter (default is 100, try 50 or 25)

Q: Analysis takes too long
A: Use fast mode for instant results, or reduce commit count

Q: File not found errors
A: Ensure you're in a git repository with commit history

Q: MCP tools not showing in Copilot
A: Verify MCP is enabled in VS Code settings and restart VS Code

Getting Help

Architecture

Agent-Based Design

┌─────────────────┐
│   AI Agent      │
│ (Claude/Copilot)│
│                 │
│ ┌─────────────┐ │
│ │  Analysis   │ │
│ │  Engine     │ │
│ └─────────────┘ │
└────────┬────────┘
         │ Request Data
         ↓
┌─────────────────┐
│  MCP Server     │
│                 │
│ ┌─────────────┐ │
│ │ Data Gatherer│ │
│ │ • Read git  │ │
│ │ • Extract   │ │
│ │ • Structure │ │
│ └─────────────┘ │
└────────┬────────┘
         │ Read
         ↓
┌─────────────────┐
│  Git Repository │
└─────────────────┘

Benefits of This Architecture

Separation of Concerns: Data gathering vs analysis
Flexibility: Works with any AI agent
Transparency: User sees and controls analysis
Security: No API keys to manage
Cost: Uses existing AI subscription

What's New in v3.0

Major Changes

✅ Agent-Based Architecture - AI agent analyzes instead of direct API calls
✅ No API Key Required - Uses agent's existing authentication
✅ Removed Dependency - @anthropic-ai/sdk no longer needed
✅ Simplified Setup - Zero configuration required
✅ Better Transparency - You see the analysis process
✅ Universal Compatibility - Works with Claude, Copilot, and more

Migration from v2.0

No breaking changes for fast mode tools. Smart tools now:

Return data instead of generating files automatically
Require you to analyze and respond
Optionally generate files from your analysis

See CHANGELOG.md for details.

Contributing

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

License

MIT License - see LICENSE file for details.

Author

Pramod Kumar Yadav

Acknowledgments

Built with Model Context Protocol
Powered by AI agents (Claude, GitHub Copilot)
Inspired by the need for better project visualization

⭐ Star this repo if you find it useful!
🐛 Found a bug? Open an issue
💡 Have an idea? Start a discussion

Generate Agent Report Tool

New in v3.0: HTML Report Generation

After analyzing your git history with smart mode, use the generateAgentReport tool to create beautiful visual reports.

Usage:

@workspace Use generateAgentReport with these timeline events: [your JSON events]

Features:

📄 Interactive HTML timeline with gradient UI
📝 Markdown documentation
🎨 Responsive design with card-based layout
🗂️ Files saved in .timeline/ directory
✨ Customizable title and filename

Example Workflow:

Gather commit data:

@workspace Use generateSmartFeatureTimeline on /path/to/repo

Analyze and create timeline (you provide JSON):

[
  {
    "date": "2024-02-04",
    "title": "Feature Name",
    "description": "What was built and why",
    "category": "authentication",
    "icon": "🔐",
    "files": ["src/auth.ts"],
    "commitHashes": ["abc123"],
    "tags": ["security", "oauth"]
  }
]

Generate reports:

@workspace Use generateAgentReport with the timeline events above

Open the HTML file in your browser!

Output Files:

FEATURE_TIMELINE.html - Interactive visualization
FEATURE_TIMELINE.md - Markdown documentation