git-workreport

Git Work Report

A powerful GitHub plugin that generates AI-powered work reports from Git commit history for specified dates. Perfect for DevOps teams and development companies to track and validate work progress with intelligent summaries.

Features

• 🤖 AI-Powered Summaries: Generate intelligent summaries using Anthropic's Claude AI
• 📅 Date-based reporting: Generate reports for any specific date
• 📊 Comprehensive statistics: Track commits, total lines changed, and authors
• 🎨 Multiple formats: Output in text, JSON, or Markdown formats
• ⚡ Fast and efficient: Built with TypeScript and optimized for performance
• 🌍 Timezone support: Handle different timezones for accurate reporting

Installation

npm install -g git-workreport

Quick Start

Basic Usage

Generate a work report for today:

git-workreport

Generate a work report for a specific date:

git-workreport 11/08/2025

AI-Powered Summaries

Generate a report with AI-generated summary (requires Anthropic API key):

git-workreport 11/08/2025 --anthropic-key YOUR_API_KEY

Advanced Usage

Generate a report in JSON format:

git-workreport 11/08/2025 --format json

Save report to a file:

git-workreport 11/08/2025 --output reports/work-report.txt

Generate Markdown report with AI summary:

git-workreport 11/08/2025 --format markdown --output report.md --anthropic-key YOUR_API_KEY

Command Line Options

Option	Description	Default
[date]	Date in DD/MM/YYYY format	Today
-f, --format <format>	Output format: text, json, or markdown	text
-o, --output <file>	Output file path	Console output
--no-stats	Exclude statistics from the report	false
--no-files	Exclude file lists from the report	false
--timezone <tz>	Timezone for date parsing	local
--repo <path>	Path to Git repository	Current directory
--anthropic-key <key>	Anthropic API key for AI-generated summaries	None

Examples

Example 1: Daily Work Report with AI Summary

git-workreport 15/08/2025 --anthropic-key YOUR_API_KEY

Output:

================================================================================
GIT WORK REPORT - 15/08/2025
================================================================================

SUMMARY:
  Date: 15/08/2025
  Total Commits: 8
  Total Lines Changed: 312
  Authors: John Doe, Jane Smith

AI-GENERATED SUMMARY:
  Implemented user authentication system with login/logout functionality and 
  responsive design improvements. Added comprehensive test coverage and fixed 
  several UI bugs across the application.

STATISTICS:
  Insertions: 245 lines
  Deletions: 67 lines
  Net Changes: 178 lines
  Average Commits per Author: 4.00

================================================================================
Report generated on 8/15/2025, 5:30:45 PM

Example 2: JSON Report

git-workreport 15/08/2025 --format json --output report.json

Output:

{
  "date": "15/08/2025",
  "totalCommits": 8,
  "totalInsertions": 245,
  "totalDeletions": 67,
  "authors": ["John Doe", "Jane Smith"],
  "aiSummary": "Implemented user authentication system with login/logout functionality and responsive design improvements. Added comprehensive test coverage and fixed several UI bugs across the application.",
  "totalLinesChanged": 312
}

Example 3: Markdown Report

git-workreport 15/08/2025 --format markdown --output report.md

Output:

# Git Work Report - 15/08/2025

**Generated:** 8/15/2025, 5:30:45 PM

## Summary

| Metric | Value |
|--------|-------|
| Date | 15/08/2025 |
| Total Commits | 8 |
| Total Lines Changed | 312 |
| Authors | John Doe, Jane Smith |

## AI-Generated Summary

> Implemented user authentication system with login/logout functionality and 
> responsive design improvements. Added comprehensive test coverage and fixed 
> several UI bugs across the application.

## Statistics

- **Insertions:** 245 lines
- **Deletions:** 67 lines
- **Net Changes:** 178 lines
- **Average Commits per Author:** 4.00

AI Summary Features

The AI-powered summary feature uses Anthropic's Claude AI to analyze commit messages and generate intelligent summaries of daily work. The AI:

• Analyzes commit messages to understand what work was accomplished
• Provides context about the types of changes made
• Summarizes in simple language that's easy to understand
• Focuses on the most important changes from the day
• Falls back gracefully to basic summaries when AI is not available

To use AI summaries, you'll need an Anthropic API key. Get one at https://console.anthropic.com/.

Use Cases

For Development Companies

• Client Reporting: Generate intelligent daily/weekly work summaries for clients
• Progress Tracking: Monitor team productivity with AI-generated insights
• Project Validation: Verify work completed on specific dates with clear summaries
• Time Tracking: Support time tracking systems with intelligent commit analysis

For DevOps Teams

• Deployment Validation: Verify what code was deployed with AI summaries
• Release Notes: Generate intelligent release notes from commit history
• Audit Trails: Create audit reports with clear work descriptions
• Performance Monitoring: Track code changes with contextual summaries

Programmatic Usage

You can also use the package programmatically:

import { GitAnalyzer, ReportGenerator } from 'git-workreport';

async function generateReport() {
  const analyzer = new GitAnalyzer();
  const generator = new ReportGenerator();
  
  const report = await analyzer.generateWorkReport('15/08/2025', {
    anthropicApiKey: 'YOUR_API_KEY'
  });
  const formattedReport = generator.generateReport(report, { format: 'markdown' });
  
  console.log(formattedReport);
}

Requirements

• Node.js >= 16.0.0
• Git repository (local or remote)
• Git command line tools
• Anthropic API key (optional, for AI summaries)

Troubleshooting

Common Issues

• "not a git repository" error

  • Make sure you're in a Git repository directory
  • Use --repo <path> to specify repository location

• "Invalid date format" error

  • Use DD/MM/YYYY format (e.g., 15/08/2025)
  • Alternative formats: YYYY-MM-DD, MM/DD/YYYY

• No commits found

  • Verify the date has commits
  • Check timezone settings with --timezone option

• AI summary not working

  • Ensure you have a valid Anthropic API key
  • Check your internet connection
  • The tool will fall back to basic summaries if AI is unavailable

Getting Help

git-workreport --help

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

License

MIT License - see LICENSE file for details