git-hotspot-ai 0.1.0

Analyze git hotspots and trigger AI post-processing

Git Hotspot AI

A lightweight CLI tool for analyzing git hotspots and triggering AI post-processing tasks.

Features

• Git Hotspot Analysis: Identify the most frequently modified files in your repository
• Flexible Filtering: Filter by time range, file patterns, and minimum commit counts
• AI Task Integration: Trigger AI-powered analysis tasks on hotspot files
• Configurable Output: Select top files by percentage or absolute count
• Dry Run Mode: Preview results without executing AI tasks

Installation

From Source

git clone https://github.com/yourusername/git-hotspot-ai.git
cd git-hotspot-ai
pip install -e .

Development Installation

git clone https://github.com/yourusername/git-hotspot-ai.git
cd git-hotspot-ai
pip install -e ".[dev]"

Environment Setup

Required: Before using git-hotspot-ai, you must configure the cursor-agent path:

# Set the environment variable to point to your cursor-agent executable
export CURSOR_AGENT_PATH=/path/to/cursor-agent

# Or if cursor-agent is in your PATH:
export CURSOR_AGENT_PATH=$(which cursor-agent)

# Add to your shell profile for persistence:
echo 'export CURSOR_AGENT_PATH=$(which cursor-agent)' >> ~/.bashrc
# or for zsh:
echo 'export CURSOR_AGENT_PATH=$(which cursor-agent)' >> ~/.zshrc

Usage

Basic Usage

# analyze current directory
git-hotspot-ai

# analyze specific repository
git-hotspot-ai --repo /path/to/repo

# show top 20 files
git-hotspot-ai --top 20

# show top 15% of files
git-hotspot-ai --top 15%

# dry run (preview without AI tasks)
git-hotspot-ai --dry-run

Advanced Options

# analyze files modified in the last 6 months
git-hotspot-ai --since "6 months ago"

# ignore test files and documentation
git-hotspot-ai --ignore "tests/*,docs/*,*.md"

# only consider files with at least 5 commits
git-hotspot-ai --min-commits 5

# run specific AI tasks
git-hotspot-ai --tasks "annotate,structure,performance"

Command Line Options

Option	Description	Default
--repo	Path to git repository	Current directory
--top	Top files to select (count or percentage)	10%
--tasks	Comma-separated AI tasks	annotate,structure,skills,performance,mvp
--since	Git time filter (e.g., "6 months ago")	None
--dry-run	Preview without AI tasks	False
--ignore	Glob patterns to ignore	Empty
--min-commits	Minimum commit count	1
--cursor-agent-path	Path to cursor-agent executable	CURSOR_AGENT_PATH env var

AI Tasks

The tool supports the following AI tasks:

• annotate: 为代码添加详细的注释和文档，提高代码可读性
• structure: 分析代码结构，识别重构机会和架构改进建议
• skills: 识别代码所需的技能和专业知识，分析技术栈和最佳实践
• performance: 分析性能特征，识别瓶颈并提出优化建议
• mvp: 生成最小可行产品建议，分析核心功能和简化方案

Each task generates specific prompts tailored to the file's git hotspot metrics (commit frequency, line changes, etc.).

How It Works

1. Git Analysis: Uses git log --numstat to collect file modification statistics
2. Scoring: Combines commit count and line changes to score files
3. Filtering: Applies time range, ignore patterns, and minimum commit filters
4. Selection: Selects top files based on percentage or count
5. AI Dispatch: Triggers configured AI tasks on selected files

Scoring Algorithm

Files are scored using the formula:

score = commit_count + 0.1 * line_changes

This balances the frequency of changes with the magnitude of changes.

Examples

Find Most Active Files

# top 10 most active files
git-hotspot-ai --top 10

# top 5% of files with at least 3 commits
git-hotspot-ai --top 5% --min-commits 3

Analyze Recent Changes

# files modified in last 3 months
git-hotspot-ai --since "3 months ago"

# recent changes excluding tests
git-hotspot-ai --since "1 month ago" --ignore "test_*,*_test.py"

Development Workflow

# preview what would be analyzed
git-hotspot-ai --dry-run --top 20

# run AI analysis on top files
git-hotspot-ai --top 20 --tasks "annotate,structure"

# use custom cursor-agent path
git-hotspot-ai --cursor-agent-path /usr/local/bin/cursor-agent --tasks "performance"

Cursor Agent Integration

The tool integrates with cursor-agent CLI to perform AI analysis tasks:

# ensure cursor-agent is available
export CURSOR_AGENT_PATH=$(which cursor-agent)

# run analysis with specific tasks
git-hotspot-ai --tasks "annotate,performance" --top 5

# dry run to see what files would be processed
git-hotspot-ai --dry-run --tasks "structure,skills"

Each task generates contextual prompts that include:

• File path and git hotspot metrics
• Task-specific analysis requirements
• Chinese language instructions for better AI understanding

Development

Running Tests

pytest

Code Formatting

black git_hotspot_ai/
isort git_hotspot_ai/

Type Checking

mypy git_hotspot_ai/

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

0.1.0

• Initial release
• Basic git hotspot analysis
• CLI interface
• AI task dispatch framework