ai-dev-pulse 1.0.0

AI-powered developer productivity dashboard with GitHub integration

  ____             _       ____                  _
 |  _ \ _   _  ___| | __  |  _ \ __ _ _ __   ___| |__
 | | | | | | |/ __| |/ /  | |_) / _` | '_ \ / __| '_ \
 | |_| | |_| | (__|   <   |  __/ (_| | | | | (__| | | |
 |____/ \__,_|\___|_|\_\  |_|   \__,_|_| |_|\___|_| |_|

  Your AI-powered engineering manager -- tracks dev productivity,
  predicts bottlenecks, and coaches your team to peak performance.

---

What is DevPulse?

DevPulse is an AI-powered developer productivity dashboard that connects to your GitHub organization and gives you deep insights into how your engineering team is performing. It tracks commits, PRs, issues, and code reviews -- then uses intelligent analysis to detect bottlenecks, predict sprint outcomes, flag burnout risk, and coach your team to peak performance.

All data stays local (SQLite). No external services. No sending your code to third-party APIs.

---

Features

GitHub Integration

• Tracks commits, pull requests, issues, and code reviews across all repos
• Supports organization and personal accounts
• Rate-limited API client with caching to respect GitHub limits

Developer Metrics

• Commits per day, active days, PR merge time, review turnaround
• Lines added/removed, issue velocity, review participation
• Per-developer and team-wide views

AI-Powered Insights

• Identifies bottlenecks (slow reviews, large PRs, weekend work patterns)
• Suggests actionable improvements for each detected issue
• Predicts sprint completion based on velocity trends
• Detects scope creep in sprints

Team Health Score

• Burnout detection: flags developers at risk based on commit patterns
• Workload balance: measures how evenly work is distributed
• Collaboration score: tracks code review participation
• Velocity trend: growing, stable, or declining

Sprint Analytics

• Sprint burndown charts rendered in ASCII
• Velocity tracking across multiple sprints
• Sprint completion prediction with confidence scores
• Scope creep detection

Code Quality Trends

• Track test coverage, bug rate, and tech debt score over time
• Per-repo quality scores computed from commit/PR data

Activity Heatmap

• GitHub-style contribution graph rendered directly in your terminal
• 365-day or custom range views
• Per-developer heatmaps

Reports

• Daily, weekly, and monthly reports
• Multiple output formats: Terminal (Rich), Markdown, JSON, HTML
• Auto-generated with AI insights and recommendations
• Save to files or output to stdout

Goal Tracking

• Set measurable targets (e.g., "10 commits/day", "< 24h PR merge time")
• Track progress with percentage completion
• Get AI coaching with specific advice per goal

REST API

• Full FastAPI web server with OpenAPI docs
• Every feature accessible via JSON endpoints
• CORS enabled for web dashboard integration

---

Screenshots

Terminal Dashboard

  ____             _       ____                  _
 |  _ \ _   _  ___| | __  |  _ \ __ _ _ __   ___| |__
 | | | | | | |/ __| |/ /  | |_) / _` | '_ \ / __| '_ \
 | |_| | |_| | (__|   <   |  __/ (_| | | | | (__| | | |
 |____/ \__,_|\___|_|\_\  |_|   \__,_|_| |_|\___|_| |_|

────────────────────── Overview ───────────────────────

  Date: 2026-04-10
  4 commit(s), 2 PR(s) opened, 1 PR(s) merged

───────────────────── Team Metrics ─────────────────────

┏━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━┳━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ Developer    ┃ Commits ┃ C/D ┃ PRs ┃ Reviews ┃ Merge(h) ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━╇━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ Alice        │       3 │ 0.1 │   2 │       1 │     24.0 │
│ Bob          │       1 │ 0.0 │   1 │       1 │     12.0 │
└──────────────┴─────────┴─────┴─────┴─────────┴──────────┘

───────────────────── Team Health ──────────────────────

  Health Score: 72/100
  Workload Balance: 65%
  Collaboration: 80%
  Velocity: stable

  Burnout Risk:
    Alice          ##################-- 90%
    Bob            ####---------------- 20%

──────────────────── AI Insights ───────────────────────

  !! Average PR merge time is 24h. Room for improvement.
     -> Set up PR size guidelines and automated review reminders.

  *  Team health looks good! Keep up the great work.

──────────────────── Activity Heatmap ──────────────────

     Apr May Jun Jul Aug Sep Oct Nov Dec Jan Feb Mar Apr
Mon  .  oo +. .. .o .+ .. o. .. +. .. .o .. .+ .o .. .
Wed  .  .. .+ .. o. .. +. .. .o .. +. .. .o .. .+ .. .
Fri  .  o. .. +. .. .o .. +. .. .o .. +. .. .o .. .+ ..
Sun  .  .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..

  Total: 847 commits across 198 active days

---

Quick Start

Installation

# Install from PyPI
pip install ai-dev-pulse

# Or clone the repository
git clone https://github.com/theihtisham/dev-pulse.git
cd dev-pulse

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Configuration

# Set your GitHub token (required for GitHub integration)
export DEVPULSE_GITHUB_TOKEN=ghp_your_token_here

# Optional: set your username or organization
export DEVPULSE_GITHUB_USERNAME=your_username
# or
export DEVPULSE_GITHUB_ORG=your_org

Sync Data

# Sync all accessible repositories
devpulse sync --all

# Sync specific repos
devpulse sync --repos owner/repo1 owner/repo2

# Sync data from the last 90 days
devpulse sync --all --since 2026-01-10

View Dashboard

# Full interactive dashboard
devpulse dashboard

# Focus on a specific developer
devpulse dashboard --author Alice

# Focus on a specific repo
devpulse dashboard --repo myorg/myrepo

---

CLI Commands

# Sync GitHub data
devpulse sync --all

# Reports
devpulse daily                          # Today's report
devpulse daily --date 2026-04-01        # Specific date
devpulse daily --format json            # JSON output
devpulse daily --format html --save     # Save as HTML
devpulse weekly                         # This week's report
devpulse monthly                        # This month's report

# Metrics
devpulse metrics --author Alice --days 30   # Developer metrics
devpulse metrics --days 7                   # Team metrics (last week)

# AI Insights
devpulse insights --days 30

# Team Health
devpulse health --days 30

# Activity Heatmap
devpulse heatmap --days 365
devpulse heatmap --author Alice

# Goals
devpulse goals add --title "10 commits/day" --target 10 --metric commits_per_day
devpulse goals list
devpulse goals coach                     # Get AI coaching
devpulse goals delete 1                  # Remove a goal

# Sprint Tracking
devpulse sprint snapshot --name "Sprint 1" --total 30 --completed 10
devpulse sprint burndown --name "Sprint 1"
devpulse sprint predict --name "Sprint 1" --total 30 --elapsed 5 --duration 10

# Code Quality
devpulse quality --repo myorg/myrepo --days 30

# Start API Server
devpulse serve --port 8742

# Interactive Dashboard
devpulse dashboard

---

REST API

Start the API server:

devpulse serve

Then access:

Endpoint	Method	Description
GET /	GET	Health check
GET /api/commits	GET	List commits
GET /api/commits/heatmap	GET	Commit heatmap data
GET /api/pull-requests	GET	List pull requests
GET /api/issues	GET	List issues
GET /api/reviews	GET	List reviews
GET /api/metrics	GET	Team metrics
GET /api/metrics/{author}	GET	Developer metrics
GET /api/health	GET	Team health analysis
GET /api/insights	GET	AI-powered insights
GET /api/goals	GET	List goals
POST /api/goals	POST	Create a goal
DELETE /api/goals/{id}	DELETE	Delete a goal
GET /api/goals/coach	GET	AI goal coaching
POST /api/sprints/snapshot	POST	Record sprint snapshot
GET /api/sprints/{name}/burndown	GET	Sprint burndown data
GET /api/sprints/{name}/predict	GET	Sprint prediction
POST /api/quality/snapshot	POST	Record quality snapshot
GET /api/quality	GET	Quality trends
GET /api/quality/{repo}/score	GET	Quality score
GET /api/reports/daily	GET	Daily report
GET /api/reports/weekly	GET	Weekly report
GET /api/reports/monthly	GET	Monthly report

Interactive docs available at http://localhost:8742/docs

---

Configuration

All settings are configured via environment variables with the DEVPULSE_ prefix:

Variable	Default	Description
DEVPULSE_GITHUB_TOKEN	(required)	GitHub personal access token
DEVPULSE_GITHUB_USERNAME		GitHub username
DEVPULSE_GITHUB_ORG		GitHub organization
DEVPULSE_GITHUB_REPOS		Comma-separated repo list
DEVPULSE_DATABASE_PATH	./devpulse_data/devpulse.db	SQLite database path
DEVPULSE_API_PORT	8742	API server port
DEVPULSE_GITHUB_RATE_LIMIT_RPM	40	Max GitHub API requests per minute
DEVPULSE_BURNOUT_THRESHOLD	0.75	Burnout risk threshold (0-1)
DEVPULSE_LOG_LEVEL	INFO	Logging level

---

Architecture

devpulse/
  core/
    config.py           # Settings (env vars, defaults)
    database.py         # SQLite layer (all CRUD)
    models.py           # Pydantic data models
    github_client.py    # GitHub API client (rate-limited, cached)
    analytics.py        # Analytics engine (metrics, insights, predictions)
    report_generator.py # Report generation (Markdown, JSON, HTML)
  cli/
    main.py             # Click CLI commands
    dashboard.py        # Interactive terminal dashboard
    render.py           # Rich rendering helpers (heatmap, charts)
  api/
    app.py              # FastAPI REST API server
  templates/
    report.html         # HTML report template
tests/
  conftest.py           # Shared fixtures
  test_database.py      # Database layer tests
  test_analytics.py     # Analytics engine tests
  test_report_generator.py  # Report generation tests
  test_api.py           # API endpoint tests
  test_config.py        # Configuration tests
  test_models.py        # Model validation tests
  test_cli.py           # CLI command tests

---

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=devpulse --cov-report=term-missing

# Run specific test file
pytest tests/test_analytics.py -v

# Run with verbose output
pytest -v --tb=short

---

Security

• GitHub tokens are read from environment variables only -- never stored in the database or logs
• All API requests use HTTPS
• Rate limiting prevents accidental GitHub API abuse
• No personal data is logged when DEVPULSE_REDACT_SENSITIVE=true
• SQLite database uses WAL mode for safe concurrent access
• Input validation via Pydantic on all API endpoints

---

Tech Stack

Component	Technology
Language	Python 3.10+
CLI	Click + Rich
API	FastAPI + Uvicorn
Database	SQLite3 (WAL mode)
Data Models	Pydantic v2
Templates	Jinja2
Testing	pytest + httpx
HTTP Client	requests

---

License

MIT License. See LICENSE for details.

---

Built with passion for developer productivity.
DevPulse -- Your AI-powered engineering manager.