gitpulse-ai 0.1.0__tar.gz

gitpulse_ai-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+
+# Environment
+.env
+.env.*
+.venv/
+venv/
+env/
+
+# Claude Code
+.claude/
+
+# Generated reports
+*-report.json
+
+# Internal dev docs
+docs/superpowers/

gitpulse_ai-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to git-pulse are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-23
+
+Initial release.
+
+### Added
+
+- `git-pulse analyze` — walks git history and reports development hotspots with
+  LLM-generated insights across five categories: rework reduction, codebase
+  health, prompt guidance, agent effectiveness, and workflow optimization.
+- Deterministic collector layer: git history walking, spatiotemporal hotspot
+  clustering, file churn, change velocity, rework rate, and work-session
+  analysis.
+- Coding-agent attribution detection from commit metadata (`Co-Authored-By`,
+  bracket tags, `aider:` prefixes).
+- LLM analyst layer via [LiteLLM](https://docs.litellm.ai/), supporting 100+
+  providers.
+- Output renderers: rich terminal and JSON.
+- TOML configuration via `.gitpulse.toml` or `~/.config/gitpulse/config.toml`.
+
+[0.1.0]: https://github.com/srikanth1003/git-pulse/releases/tag/v0.1.0

gitpulse_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 git-pulse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gitpulse_ai-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.5
+Name: gitpulse-ai
+Version: 0.1.0
+Summary: Analyze git repo history for development hotspots with LLM-powered insights
+Project-URL: Homepage, https://github.com/srikanth1003/git-pulse
+Project-URL: Repository, https://github.com/srikanth1003/git-pulse
+Project-URL: Issues, https://github.com/srikanth1003/git-pulse/issues
+Project-URL: Changelog, https://github.com/srikanth1003/git-pulse/blob/main/CHANGELOG.md
+Author: srikanth1003
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,code-analysis,code-quality,coding-agents,developer-productivity,git,git-history,hotspots,llm,technical-debt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: litellm>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# git-pulse
+
+**Analyze git repository history for development hotspots and get LLM-powered insights to optimize your workflow.**
+
+git-pulse examines your commit history to find rework patterns, codebase health issues, and — when coding agents are detected — specific prompt engineering guidance to reduce wasted iterations. It works on any git repo, with any LLM provider.
+
+## What It Does
+
+git-pulse reads your git history and produces actionable insights across five categories:
+
+| Category | What It Finds |
+|----------|--------------|
+| **Rework Reduction** | Files rewritten multiple times — what went wrong and how to get it right faster |
+| **Codebase Health** | Chronic hotspots, architectural issues causing repeated churn |
+| **Prompt Guidance** | Specific before/after prompt examples when coding agents are detected (Co-Authored-By, aider tags, etc.) |
+| **Agent Effectiveness** | How well agents are being utilized — where they struggle or excel |
+| **Workflow Optimization** | Session patterns, productivity signals, process improvements |
+
+### Agent-Aware Analysis
+
+git-pulse auto-detects coding agent attribution from commit metadata — `Co-Authored-By: Claude`, `[copilot]`, `aider:` tags, and more. When agent commits are found, it provides **prompt guidance** with realistic bad/better prompt examples showing exactly what to change in how you talk to your agent.
+
+## Install
+
+```bash
+pip install git-pulse-cli
+```
+
+Requires Python 3.10+. The installed command is `git-pulse`.
+
+## Quick Start
+
+```bash
+# Analyze current repo (last 30 days)
+git-pulse analyze .
+
+# Analyze a specific repo, last 14 days
+git-pulse analyze /path/to/repo --days 14
+
+# Last 50 commits only
+git-pulse analyze . --commits 50
+
+# JSON output
+git-pulse analyze . --json
+
+# Save report to file
+git-pulse analyze . --output report.json
+
+# Use a specific model
+git-pulse analyze . --model openai/gpt-4o
+
+# Show raw collector metrics alongside LLM insights
+git-pulse analyze . --verbose
+```
+
+## Example Output
+
+```
+────────────────────────────────────────────────────────────────────────────────
+ Git-Pulse Report — my-project (main)
+ 19 days · 100 commits · 242 files changed
+────────────────────────────────────────────────────────────────────────────────
+
+╭────────────────────────────────── Summary ───────────────────────────────────╮
+│ Repository shows intensive development with 100 commits across 242 files.   │
+│ High rework rate (40%) suggests agent prompts need improvement, with        │
+│ multiple iterations on workflow configuration and model updates.             │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+Top Actions
+  1. Create design documents before implementing GitHub Actions workflows
+  2. Establish centralized model configuration to reduce scattered updates
+  3. Improve agent prompts with dependency analysis before changes
+
+───────────────────────  Rework Reduction (2 insights)  ────────────────────────
+
+  [HIGH] GitHub Workflows Churning Through Multiple Iterations
+    .github/workflows/deploy.yml modified 9 times in 2.4 hours
+    Same file tweaked for permissions, triggers, and comments repeatedly
+  → Plan workflow requirements upfront. Create a design doc specifying trigger
+  events, permissions, and behavior before coding.
+
+────────────────────────  Prompt Guidance (1 insight)  ────────────────────────
+
+  [HIGH] Workflow Configuration Requires Context and Constraints
+    PROBLEM: Developer asked agent to 'create GitHub workflow' without
+    specifying security constraints or existing patterns.
+
+    BAD PROMPT EXAMPLE:
+  ╭──────────────────────────────────────────────────────────────────────────╮
+  │  Create a GitHub workflow that runs tests automatically.                 │
+  ╰──────────────────────────────────────────────────────────────────────────╯
+
+    BETTER PROMPT EXAMPLE:
+  ╭──────────────────────────────────────────────────────────────────────────╮
+  │  Create a GitHub workflow for CI. Before you start, look at our         │
+  │  existing .github/workflows/ to understand our patterns for             │
+  │  permissions and triggers. Use contents:read permission. Follow the     │
+  │  same job naming pattern as deploy.yml. If you're unsure about which    │
+  │  events to use, ask me rather than guessing.                            │
+  ╰──────────────────────────────────────────────────────────────────────────╯
+
+    WHY THIS WORKS: Points to existing workflows to learn patterns, sets
+    explicit security constraints, and prevents the agent from making
+    permission guesses that need rework.
+```
+
+## LLM Provider Setup
+
+git-pulse uses [LiteLLM](https://docs.litellm.ai/) under the hood, so it works with 100+ LLM providers out of the box. Set the appropriate environment variable for your provider:
+
+```bash
+# Anthropic (default model: claude-sonnet-4-20250514)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+git-pulse analyze . --model openai/gpt-4o
+
+# AWS Bedrock
+export AWS_PROFILE=my-profile
+git-pulse analyze . --model bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0
+
+# Any LiteLLM-supported provider
+git-pulse analyze . --model <provider>/<model-id>
+```
+
+## Configuration
+
+git-pulse looks for TOML config files in this order:
+
+1. `--config` flag (explicit path)
+2. `.gitpulse.toml` in the repo root
+3. `~/.config/gitpulse/config.toml`
+4. Built-in defaults
+
+Example `.gitpulse.toml`:
+
+```toml
+[llm]
+model = "anthropic/claude-sonnet-4-20250514"
+
+[analysis]
+default_days = 30
+max_hotspots = 20
+exclude = ["*.lock", "package-lock.json", "*.generated.*"]
+```
+
+## CLI Options
+
+```
+git-pulse analyze [PATH] [OPTIONS]
+
+Arguments:
+  PATH                  Path to a git repository [default: .]
+
+Options:
+  --days INTEGER        Analyze last N days of history
+  --commits INTEGER     Analyze last N commits
+  --branch TEXT         Branch to analyze (default: current)
+  --include TEXT        Only analyze files matching glob (repeatable)
+  --exclude TEXT        Skip files matching glob (repeatable)
+  --max-hotspots INT    Max hotspots to send to LLM
+  --model TEXT          LiteLLM model string
+  --json                Output JSON instead of rich terminal
+  --output TEXT         Write report to file
+  --verbose             Show raw collector metrics
+  --config TEXT         Path to config file
+```
+
+## How It Works
+
+git-pulse has a two-layer architecture:
+
+```
+Git History ──► Collector Layer ──► Structured Report ──► Analyst (LLM) ──► Insights
+                  │                                          │
+                  ├─ GitHistoryCollector                      ├─ LiteLLM (any provider)
+                  ├─ HotspotDetector (spatiotemporal)         └─ Categorized insights
+                  └─ MetricsCalculator
+```
+
+**Collector Layer** (deterministic, no LLM):
+- Walks git history, extracts diffs, detects agent attribution
+- Clusters modifications by file + spatial/temporal proximity into hotspots
+- Computes metrics: file churn, change velocity, rework rate, session analysis
+
+**Analyst Layer** (LLM-powered):
+- Receives the structured collector report
+- Produces categorized insights with evidence and recommendations
+- Generates specific prompt guidance when agent attribution is detected
+
+## Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/srikanth1003/git-pulse.git
+cd git-pulse
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run on any repo
+git-pulse analyze /path/to/any/repo --days 14
+```
+
+## License
+
+MIT

gitpulse_ai-0.1.0/README.md

@@ -0,0 +1,210 @@
+# git-pulse
+
+**Analyze git repository history for development hotspots and get LLM-powered insights to optimize your workflow.**
+
+git-pulse examines your commit history to find rework patterns, codebase health issues, and — when coding agents are detected — specific prompt engineering guidance to reduce wasted iterations. It works on any git repo, with any LLM provider.
+
+## What It Does
+
+git-pulse reads your git history and produces actionable insights across five categories:
+
+| Category | What It Finds |
+|----------|--------------|
+| **Rework Reduction** | Files rewritten multiple times — what went wrong and how to get it right faster |
+| **Codebase Health** | Chronic hotspots, architectural issues causing repeated churn |
+| **Prompt Guidance** | Specific before/after prompt examples when coding agents are detected (Co-Authored-By, aider tags, etc.) |
+| **Agent Effectiveness** | How well agents are being utilized — where they struggle or excel |
+| **Workflow Optimization** | Session patterns, productivity signals, process improvements |
+
+### Agent-Aware Analysis
+
+git-pulse auto-detects coding agent attribution from commit metadata — `Co-Authored-By: Claude`, `[copilot]`, `aider:` tags, and more. When agent commits are found, it provides **prompt guidance** with realistic bad/better prompt examples showing exactly what to change in how you talk to your agent.
+
+## Install
+
+```bash
+pip install git-pulse-cli
+```
+
+Requires Python 3.10+. The installed command is `git-pulse`.
+
+## Quick Start
+
+```bash
+# Analyze current repo (last 30 days)
+git-pulse analyze .
+
+# Analyze a specific repo, last 14 days
+git-pulse analyze /path/to/repo --days 14
+
+# Last 50 commits only
+git-pulse analyze . --commits 50
+
+# JSON output
+git-pulse analyze . --json
+
+# Save report to file
+git-pulse analyze . --output report.json
+
+# Use a specific model
+git-pulse analyze . --model openai/gpt-4o
+
+# Show raw collector metrics alongside LLM insights
+git-pulse analyze . --verbose
+```
+
+## Example Output
+
+```
+────────────────────────────────────────────────────────────────────────────────
+ Git-Pulse Report — my-project (main)
+ 19 days · 100 commits · 242 files changed
+────────────────────────────────────────────────────────────────────────────────
+
+╭────────────────────────────────── Summary ───────────────────────────────────╮
+│ Repository shows intensive development with 100 commits across 242 files.   │
+│ High rework rate (40%) suggests agent prompts need improvement, with        │
+│ multiple iterations on workflow configuration and model updates.             │
+╰──────────────────────────────────────────────────────────────────────────────╯
+
+Top Actions
+  1. Create design documents before implementing GitHub Actions workflows
+  2. Establish centralized model configuration to reduce scattered updates
+  3. Improve agent prompts with dependency analysis before changes
+
+───────────────────────  Rework Reduction (2 insights)  ────────────────────────
+
+  [HIGH] GitHub Workflows Churning Through Multiple Iterations
+    .github/workflows/deploy.yml modified 9 times in 2.4 hours
+    Same file tweaked for permissions, triggers, and comments repeatedly
+  → Plan workflow requirements upfront. Create a design doc specifying trigger
+  events, permissions, and behavior before coding.
+
+────────────────────────  Prompt Guidance (1 insight)  ────────────────────────
+
+  [HIGH] Workflow Configuration Requires Context and Constraints
+    PROBLEM: Developer asked agent to 'create GitHub workflow' without
+    specifying security constraints or existing patterns.
+
+    BAD PROMPT EXAMPLE:
+  ╭──────────────────────────────────────────────────────────────────────────╮
+  │  Create a GitHub workflow that runs tests automatically.                 │
+  ╰──────────────────────────────────────────────────────────────────────────╯
+
+    BETTER PROMPT EXAMPLE:
+  ╭──────────────────────────────────────────────────────────────────────────╮
+  │  Create a GitHub workflow for CI. Before you start, look at our         │
+  │  existing .github/workflows/ to understand our patterns for             │
+  │  permissions and triggers. Use contents:read permission. Follow the     │
+  │  same job naming pattern as deploy.yml. If you're unsure about which    │
+  │  events to use, ask me rather than guessing.                            │
+  ╰──────────────────────────────────────────────────────────────────────────╯
+
+    WHY THIS WORKS: Points to existing workflows to learn patterns, sets
+    explicit security constraints, and prevents the agent from making
+    permission guesses that need rework.
+```
+
+## LLM Provider Setup
+
+git-pulse uses [LiteLLM](https://docs.litellm.ai/) under the hood, so it works with 100+ LLM providers out of the box. Set the appropriate environment variable for your provider:
+
+```bash
+# Anthropic (default model: claude-sonnet-4-20250514)
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI
+export OPENAI_API_KEY=sk-...
+git-pulse analyze . --model openai/gpt-4o
+
+# AWS Bedrock
+export AWS_PROFILE=my-profile
+git-pulse analyze . --model bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0
+
+# Any LiteLLM-supported provider
+git-pulse analyze . --model <provider>/<model-id>
+```
+
+## Configuration
+
+git-pulse looks for TOML config files in this order:
+
+1. `--config` flag (explicit path)
+2. `.gitpulse.toml` in the repo root
+3. `~/.config/gitpulse/config.toml`
+4. Built-in defaults
+
+Example `.gitpulse.toml`:
+
+```toml
+[llm]
+model = "anthropic/claude-sonnet-4-20250514"
+
+[analysis]
+default_days = 30
+max_hotspots = 20
+exclude = ["*.lock", "package-lock.json", "*.generated.*"]
+```
+
+## CLI Options
+
+```
+git-pulse analyze [PATH] [OPTIONS]
+
+Arguments:
+  PATH                  Path to a git repository [default: .]
+
+Options:
+  --days INTEGER        Analyze last N days of history
+  --commits INTEGER     Analyze last N commits
+  --branch TEXT         Branch to analyze (default: current)
+  --include TEXT        Only analyze files matching glob (repeatable)
+  --exclude TEXT        Skip files matching glob (repeatable)
+  --max-hotspots INT    Max hotspots to send to LLM
+  --model TEXT          LiteLLM model string
+  --json                Output JSON instead of rich terminal
+  --output TEXT         Write report to file
+  --verbose             Show raw collector metrics
+  --config TEXT         Path to config file
+```
+
+## How It Works
+
+git-pulse has a two-layer architecture:
+
+```
+Git History ──► Collector Layer ──► Structured Report ──► Analyst (LLM) ──► Insights
+                  │                                          │
+                  ├─ GitHistoryCollector                      ├─ LiteLLM (any provider)
+                  ├─ HotspotDetector (spatiotemporal)         └─ Categorized insights
+                  └─ MetricsCalculator
+```
+
+**Collector Layer** (deterministic, no LLM):
+- Walks git history, extracts diffs, detects agent attribution
+- Clusters modifications by file + spatial/temporal proximity into hotspots
+- Computes metrics: file churn, change velocity, rework rate, session analysis
+
+**Analyst Layer** (LLM-powered):
+- Receives the structured collector report
+- Produces categorized insights with evidence and recommendations
+- Generates specific prompt guidance when agent attribution is detected
+
+## Development
+
+```bash
+# Clone and install in dev mode
+git clone https://github.com/srikanth1003/git-pulse.git
+cd git-pulse
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run on any repo
+git-pulse analyze /path/to/any/repo --days 14
+```
+
+## License
+
+MIT

gitpulse_ai-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitpulse-ai"
+dynamic = ["version"]
+description = "Analyze git repo history for development hotspots with LLM-powered insights"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [
+    { name = "srikanth1003" },
+]
+keywords = [
+    "git",
+    "git-history",
+    "code-analysis",
+    "code-quality",
+    "hotspots",
+    "technical-debt",
+    "developer-productivity",
+    "llm",
+    "ai",
+    "coding-agents",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.9.0",
+    "gitpython>=3.1.0",
+    "litellm>=1.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/srikanth1003/git-pulse"
+Repository = "https://github.com/srikanth1003/git-pulse"
+Issues = "https://github.com/srikanth1003/git-pulse/issues"
+Changelog = "https://github.com/srikanth1003/git-pulse/blob/main/CHANGELOG.md"
+
+[project.scripts]
+git-pulse = "git_pulse.cli:app"
+
+[tool.hatch.version]
+path = "src/git_pulse/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/git_pulse"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gitpulse_ai-0.1.0/src/git_pulse/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gitpulse_ai-0.1.0/src/git_pulse/analyst/engine.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+
+from litellm import completion
+
+from git_pulse.analyst.models import AnalystReport
+from git_pulse.analyst.prompts import build_system_prompt, build_user_prompt
+
+
+class AnalystEngine:
+    def __init__(self, model: str):
+        self.model = model
+
+    def analyze(self, report_dict: dict) -> AnalystReport:
+        """Send collector report to LLM and parse the response into an AnalystReport."""
+        system_prompt = build_system_prompt()
+        user_prompt = build_user_prompt(report_dict)
+
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        response = completion(model=self.model, messages=messages)
+        content = response.choices[0].message.content
+
+        try:
+            data = json.loads(content)
+            return AnalystReport.from_dict(data)
+        except (json.JSONDecodeError, KeyError):
+            return self._retry(messages, content)
+
+    def _retry(self, messages: list[dict], bad_content: str) -> AnalystReport:
+        """Retry with a correction prompt after malformed JSON."""
+        messages = messages + [
+            {"role": "assistant", "content": bad_content},
+            {
+                "role": "user",
+                "content": "Your response was not valid JSON. Please respond with ONLY valid JSON matching the schema from the system prompt. No markdown, no explanation.",
+            },
+        ]
+
+        response = completion(model=self.model, messages=messages)
+        content = response.choices[0].message.content
+
+        try:
+            data = json.loads(content)
+            return AnalystReport.from_dict(data)
+        except (json.JSONDecodeError, KeyError):
+            return AnalystReport(
+                summary="Failed to parse LLM response. Run with --verbose to see raw collector data.",
+                insights=[],
+                top_actions=[],
+            )