perfdive

A Golang CLI application for tracking and summarizing your work. Get quick weekly highlights or deep-dive into Jira and GitHub activity with AI-powered summaries using Ollama.

Features

Quick Highlights: Simple highlight command for instant weekly summaries with bullet points
Automatic Journaling: Maintain a running log in GitHub Gist - configure once, auto-updates forever
AI-Powered Insights: Uses Ollama to generate accomplishment summaries with "why" explanations focused on impact to Red Hat, partners, customers, and open source
Fetches Jira issues assigned to a specific user within a date range
GitHub Integration: Automatically detects and fetches context from GitHub URLs in Jira issues
Intelligent Caching: 24-hour cache for PRs/Issues and 1-hour cache for user activity to minimize API calls and improve performance
GitHub User Activity: Optional feature to fetch user's personal GitHub activity by matching their email
Uses Ollama to generate intelligent summaries of user activity with enhanced GitHub context
Supports both text and JSON output formats
Configurable via command line flags or configuration file
Built with Cobra CLI framework and Viper for configuration

Installation

Prerequisites

Go 1.25.1 or later
Access to a Jira instance with API access
Ollama running locally or accessible via network

Build from source

git clone https://github.com/redhat-best-practices-for-k8s/perfdive.git
cd perfdive
make build

Or alternatively using Go directly:

go build -o perfdive .

Makefile Targets

The project includes a Makefile with the following targets:

make build - Build the perfdive binary
make install - Build and install to ~/.local/bin (customize with PREFIX=/path)
make uninstall - Remove installed binary
make clean - Remove build artifacts
make test - Run tests
make fmt - Format Go code
make vet - Run go vet
make check - Run fmt, vet, and test
make help - Show all available targets

Quick Install:

make install
# Now you can run: perfdive highlight [email protected]

Configuration

Option 1: Configuration File

Copy the example configuration file and customize it:

cp .perfdive.yaml.example ~/.perfdive.yaml

Edit ~/.perfdive.yaml:

jira:
  url: "https://your-company.atlassian.net"
  username: "[email protected]"
  token: "your-jira-api-token"

ollama:
  url: "http://localhost:11434"

github:
  token: "your-github-token"  # Optional: for private repos or higher rate limits
  gist_url: "https://gist.github.com/username/gist-id"  # Optional: for journal feature

output:
  format: "text"  # "text" or "json"

Option 2: Command Line Flags

You can specify all configuration via command line flags:

./perfdive \
  --jira-url "https://your-company.atlassian.net" \
  --jira-username "[email protected]" \
  --jira-token "your-jira-api-token" \
  --ollama-url "http://localhost:11434" \
  --output "text" \
  [email protected] 01-01-2025 01-31-2025 llama3.2:latest

Jira API Token

To get a Jira API token:

Go to your Jira account settings
Navigate to Security → API tokens
Create a new API token
Use this token in the configuration

Note: The application uses Bearer token authentication via the jiracrawler library. Ensure your API token has the necessary permissions to read issues and user information.

GitHub Integration (Optional)

The application automatically detects GitHub URLs in Jira issue descriptions and summaries. When found, it can fetch additional context from GitHub:

Pull Request details: title, description, author, status, commit counts, file changes
Issue details: title, description, labels, status, creation/close dates
Enhanced AI summaries: GitHub context is included in Ollama prompts for richer analysis
Reference counting: Always shows count of GitHub URLs found in Jira issues

To enable GitHub integration:

Create a GitHub Personal Access Token:
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Create a new token with public_repo scope (or repo for private repositories)
- Copy the token
Add the token to your configuration or use the --github-token flag

Important: Use a Classic Personal Access Token, not a fine-grained token. Fine-grained tokens are repository-scoped and won't work with perfdive's user search and cross-repository operations.

Note: GitHub integration is optional. Without a token, the application works with public repositories with rate limiting. With a token, you get higher rate limits and access to private repositories.

GitHub Reference Status Messages

The application will show different messages based on what it finds:

Found X GitHub references in Jira issues - Always shows the count of unique GitHub URLs found
ℹ Use --github-token to fetch detailed GitHub context - When references found but no token provided
⚠ GitHub auth failed, retrying without token for public repo access... - When invalid token provided, retrying for public repos
✓ Successfully fetched details for X GitHub PRs and Y issues - When GitHub API calls succeed
⚠ Found GitHub references but couldn't fetch details (check GitHub token) - When API calls fail even without auth
No GitHub references found in Jira issues - When no GitHub URLs are detected

Automatic Retry for Public Repositories

The application intelligently handles GitHub authentication:

With valid token: Uses authenticated requests (higher rate limits, private repo access)
With invalid token: Automatically retries without authentication for public repositories
Without token: Directly accesses public repositories (with rate limiting)

This means you don't need to worry about 401 errors when accessing public GitHub repositories, even if you provide an incorrect token.

GitHub User Activity (Advanced Feature)

Beyond just fetching context from GitHub URLs found in Jira issues, perfdive can also fetch a user's personal GitHub activity:

What it provides:

Recent GitHub events (commits, PRs, issues, repository creation)
Activity correlation with the same date range as Jira analysis
Comprehensive view of both ticket work (Jira) and actual development (GitHub)

How to enable:

./perfdive [email protected] 01-01-2025 01-31-2025 llama3.2:latest \
  --github-token "your-token" \
  --github-activity

Requirements:

Requires --github-token (uses GitHub search API)
User's email must be publicly associated with their GitHub account
Some users keep emails private, which will prevent user matching

Limitations:

Only works if the user's email is public in their GitHub profile
GitHub API rate limits apply (higher with authentication)
Limited to recent activities (GitHub API typically shows last 90 days)

When it works vs doesn't:

✅ Works: User has public email in GitHub profile matching Jira email
❌ Doesn't work: User has private email settings or uses different email for GitHub
❌ Doesn't work: User doesn't have a GitHub account with that email

Usage

Quick Highlight Summary

For a quick, effortless summary of recent work, use the highlight command:

./perfdive highlight [email]

Example:

./perfdive highlight [email protected]

This command generates a concise bullet-point list showing:

Number of PRs created (merged vs open)
Number of Jira stories created and updated
AI-generated biggest accomplishment

Options:

--days or -d: Number of days to look back (default: 7)
--list or -l: List top N accomplishments instead of just the biggest (e.g., --list 5)
--github-username: Use explicit GitHub username instead of email lookup
--verbose or -v: Show detailed progress information
--clear-cache: Force refresh by clearing GitHub activity cache

Caching: perfdive automatically caches data to minimize API calls and avoid rate limits:

Jira issues: 24-hour cache (eliminates rate limit errors on repeat runs)
GitHub PRs & Issues: 24-hour cache (for analyzing Jira references)
GitHub user activity: 1-hour cache (for quick repeated highlight runs)
Cache location: ~/.perfdive/cache/
See docs/JIRA_ISSUES_CACHE.md and docs/GITHUB_ISSUES_CACHE.md for details

Automatic Journaling: If you configure github.gist_url in your config file, highlights will automatically be appended to your GitHub Gist journal. No flag needed!

Examples:

# Quick summary for the last 7 days
./perfdive highlight [email protected]

# Summary for the last 14 days
./perfdive highlight [email protected] --days 14

# Use explicit GitHub username
./perfdive highlight --github-username sebrandon1 [email protected]

# Show detailed progress (useful for debugging)
./perfdive highlight [email protected] --verbose

# Force refresh (clear cache and fetch fresh data)
./perfdive highlight [email protected] --clear-cache

# List top 5 accomplishments instead of just the biggest
./perfdive highlight [email protected] --list 5

# All commands automatically journal if gist_url is configured!

Verbose Output Example:

Generating highlight for [email protected] (10-29-2025 to 11-05-2025)
Date range: 7 days

→ Creating Jira client...
  ✓ Connected to https://issues.redhat.com
→ Creating GitHub client...
  ✓ GitHub token configured

→ Fetching Jira issues for [email protected]...
→ Fetching GitHub activity...
  ✓ Using cached GitHub activity (saves API rate limit)
  ✓ Found 5 Jira issues
  ✓ Found GitHub user 'bpalm' with 13 PRs, 2 issues

→ Generating AI summary using Ollama...
  Model: llama3.2:latest
  Endpoint: http://localhost:11434
  ✓ AI summary generated

  💡 Why this is the biggest accomplishment:
     This authentication refactor is significant because it addresses critical security 
     vulnerabilities affecting Red Hat's enterprise customers. The implementation enables 
     Red Hat's partners to integrate more securely with their IAM solutions, reduces 
     compliance risks for customer deployments, and aligns with industry-standard open 
     source authentication frameworks used across the community.

============================================================
HIGHLIGHT SUMMARY
============================================================

- Created 13 PRs in the last 7 days (5 merged, 8 open)
- Created 3 Jira stories and updated Jira 10 times
- Biggest accomplishment: Implemented critical authentication refactor

Note: When using --verbose, the AI will explain why it chose that as your biggest accomplishment, providing context on the impact for Red Hat, its partners, customers, and the open source community.

Using --list for Multiple Accomplishments:

./perfdive highlight [email protected] --list 5

Example Output:

- Created 13 PRs in the last 7 days (5 merged, 8 open)
- Created 3 Jira stories and updated Jira 10 times
- Top 5 accomplishments:
  1. Implemented GitHub caching system reducing API calls by 97%
  2. Added comprehensive rate limit handling for Jira and GitHub APIs
  3. Fixed critical authentication bug affecting multiple services
  4. Enhanced observability with detailed logging and cache statistics
  5. Improved documentation with complete caching guides

Journal Feature

The journal feature automatically maintains a running log of your highlights in a private GitHub Gist. Simply configure the gist_url once, and every highlight will be saved automatically.

Setup:

Create a new Gist on GitHub (public or private)
Copy the Gist URL (e.g., https://gist.github.com/username/abc123)

Add it to your ~/.perfdive.yaml:

github:
  token: "your-github-token"
  gist_url: "https://gist.github.com/username/abc123"

That's it! Once configured, every time you run ./perfdive highlight, it will automatically append to your journal.

Behavior:

Automatic: No flags needed, just configure gist_url once
Entries are prepended (newest first) with date headers
Existing entries for the same date range are automatically replaced with updated data
Works with any file in the Gist (prefers files with "journal" in the name)
Includes AI-generated "why" explanation for your biggest accomplishment

Example output in Gist:

## October 29, 2025 to November 5, 2025
- Created 13 PRs in the last 7 days (5 merged, 8 open)
- Created 3 Jira stories and updated Jira 10 times
- Biggest accomplishment: Implemented critical authentication refactor
  - Why: This refactor addresses a critical security vulnerability that affected multiple services, demonstrating both technical depth and cross-functional impact. The merged PRs show completed implementation across the entire authentication stack.

---

## October 22, 2025 to October 29, 2025
...

Full Analysis Mode

Basic Usage

./perfdive [email] [start-date] [end-date] [model]

Example:

./perfdive [email protected] 06-01-2025 06-31-2025 llama3.2:latest

Parameters

email: Email address of the user whose Jira issues you want to analyze
start-date: Start date in MM-DD-YYYY format
end-date: End date in MM-DD-YYYY format
model: Ollama model to use for generating summaries (e.g., llama3.2:latest, mistral, etc.)

Command Line Flags

--jira-url (-j): Jira base URL
--jira-username (-u): Jira username
--jira-token (-t): Jira API token
--ollama-url (-o): Ollama API URL (default: http://localhost:11434)
--github-token (-g): GitHub API token (optional, for private repos)
--github-activity (-a): Fetch user's GitHub activity by matching email (requires GitHub token)
--output (-f): Output format - "text" or "json" (default: text)
--rate-limit-delay (-r): Delay between Jira API requests in milliseconds (default: 500ms, increase if seeing rate limit errors)
--verbose (-v): Enable verbose output including warnings and debug information
--config: Path to config file (default: $HOME/.perfdive.yaml)

Output Formats

Text Format (Default)

Processing Jira issues for [email protected] from 01-01-2025 to 01-31-2025 using model llama3.2:latest
Testing Jira connection...
✓ Jira connection successful
Testing Ollama connection with model llama3.2:latest...
✓ Ollama connection successful
Fetching Jira issues for [email protected] from 01-01-2025 to 01-31-2025...
Found 5 issues
Found 3 GitHub references in Jira issues
ℹ Use --github-token to fetch detailed GitHub context
Generating summary using llama3.2:latest...

============================================================
SUMMARY FOR [email protected] (01-01-2025 to 01-31-2025)
============================================================
During the specified period from 01-01-2025 to 01-31-2025, [email protected] was actively involved in...

JSON Format

./perfdive --output json [email protected] 01-01-2025 01-31-2025 llama3.2:latest

{
  "summary": "During the specified period...",
  "period": "01-01-2025 to 01-31-2025", 
  "user": "[email protected]",
  "total_issues": 5,
  "key_activities": ["Bug fixes", "Feature development", "Code review"]
}

Examples

Get a quick highlight of recent work

./perfdive highlight [email protected]

Output:

- Created 13 PRs in the last 7 days (5 merged, 8 open)
- Created 3 Jira stories and updated Jira 10 times
- Biggest accomplishment: Implemented critical authentication refactor across multiple services

Keep a journal of your weekly highlights

# First time: create a new Gist on GitHub and add gist_url to config
# Then just run highlight - journaling is automatic!
./perfdive highlight [email protected]

Output:

- Created 13 PRs in the last 7 days (5 merged, 8 open)
- Created 3 Jira stories and updated Jira 10 times
- Biggest accomplishment: Implemented critical authentication refactor
  - Why: This refactor addresses a critical security vulnerability that affected multiple services, demonstrating both technical depth and cross-functional impact.

✓ Journal updated: https://gist.github.com/username/abc123

Note: With gist_url configured, journaling happens automatically. The "why" explanation is always included in journal entries, providing context for future reference.

Generate a summary for a user's work in December 2024

./perfdive [email protected] 12-01-2024 12-31-2024 llama3.2:latest

Generate a JSON summary using a specific Ollama model

./perfdive --output json [email protected] 01-01-2025 01-15-2025 mistral:latest

Use with custom Jira and Ollama endpoints

./perfdive \
  --jira-url "https://custom-jira.company.com" \
  --ollama-url "http://ollama-server:11434" \
  [email protected] 06-01-2025 06-30-2025 llama3.2:latest

Use with GitHub integration for enhanced context

./perfdive \
  --jira-url "https://issues.redhat.com" \
  --jira-username "[email protected]" \
  --jira-token "your-jira-token" \
  --github-token "your-github-token" \
  [email protected] 06-01-2025 06-30-2025 llama3.2:latest

This will automatically detect GitHub URLs in Jira issues and include PR/issue details in the summary.

Use with comprehensive GitHub activity analysis

./perfdive \
  --jira-url "https://issues.redhat.com" \
  --jira-username "[email protected]" \
  --jira-token "your-jira-token" \
  --github-token "your-github-token" \
  --github-activity \
  [email protected] 06-01-2025 06-30-2025 llama3.2:latest

This will fetch:

Jira issues assigned to the user
GitHub URLs referenced in those Jira issues
User's personal GitHub activity (commits, PRs, etc.) for the same time period
Generate a comprehensive summary correlating all data sources

Architecture

The application consists of several key components:

CLI Interface (cmd/root.go): Built with Cobra, handles command parsing and configuration
Jira Client (internal/jira/client.go): Wraps the sebrandon1/jiracrawler library for Jira API access
GitHub Client (internal/github/client.go): Detects GitHub URLs and fetches PR/issue context via GitHub API
Ollama Client (internal/ollama/client.go): Handles communication with Ollama for AI summary generation with enhanced context
Configuration: Uses Viper for flexible configuration management

Dependencies

Cobra - CLI framework
Viper - Configuration management
jiracrawler - Jira API client library

Troubleshooting

Common Issues

Jira Authentication Failed
- Verify your Jira URL, username, and API token
- Ensure your API token has the necessary permissions
Ollama Connection Failed
- Ensure Ollama is running and accessible
- Verify the Ollama URL is correct
- Check that the specified model is installed in Ollama
GitHub 401 Errors (Fixed Automatically)
- The application automatically retries without authentication for public repos
- You'll see: ⚠ GitHub auth failed, retrying without token for public repo access...
- This is normal behavior and usually resolves automatically
GitHub Rate Limit Errors (Handled Automatically)
- The application now includes intelligent rate limit handling
- What you'll see: Rate limit status displayed at startup showing remaining API calls
- Automatic waiting: If rate limited, the tool waits until the limit resets
- Automatic retries: Failed requests are retried with exponential backoff (2s, 4s, 8s)
- Tips to avoid rate limits:
  - Use --github-token for 83x more requests (5,000/hour vs 60/hour)
  - Space out multiple runs by a few minutes
  - Cache is enabled by default (1-hour TTL) to reduce API calls
- See docs/GITHUB_RATE_LIMITING_FIX.md for detailed information
No Issues Found
- Verify the user email is correct
- Check that issues exist for the user in the specified date range
- Ensure the date format is MM-DD-YYYY
GitHub User Not Found (with --github-activity)
- Error: no GitHub user found with email [email protected]
- Cause: User's email is private in GitHub settings or they use a different email
- Solutions:
  - Ask user to make their email public in GitHub profile settings
  - Try with the actual email they use for GitHub commits
  - Use without --github-activity flag for basic functionality
Date Format Errors
- Use MM-DD-YYYY format (e.g., 06-01-2025, not 6-1-2025)

Debug Mode

For additional debugging information, you can run with verbose output:

./perfdive --config ~/.perfdive.yaml [email protected] 01-01-2025 01-31-2025 llama3.2:latest

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github		.github
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

redhat-best-practices-for-k8s/perfdive

Folders and files

Latest commit

History

Repository files navigation

perfdive

Features

Installation

Prerequisites

Build from source

Makefile Targets

Configuration

Option 1: Configuration File

Option 2: Command Line Flags

Jira API Token

GitHub Integration (Optional)

GitHub Reference Status Messages

Automatic Retry for Public Repositories

GitHub User Activity (Advanced Feature)

Usage

Quick Highlight Summary

Journal Feature

Full Analysis Mode

Basic Usage

Parameters

Command Line Flags

Output Formats

Text Format (Default)

JSON Format

Examples

Get a quick highlight of recent work

Keep a journal of your weekly highlights

Generate a summary for a user's work in December 2024

Generate a JSON summary using a specific Ollama model

Use with custom Jira and Ollama endpoints

Use with GitHub integration for enhanced context

Use with comprehensive GitHub activity analysis

Architecture

Dependencies

Troubleshooting

Common Issues

Debug Mode

Contributing

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Contributors 2

Uh oh!

Languages

Packages