Perfect PR descriptions, generated with AI
Prfect is a powerful tool that analyzes your git commits and generates professional pull request descriptions using local AI models via Ollama. No more struggling with blank PR templates or forgetting what you changed!
- 🧠 AI-Powered: Uses Ollama with DeepSeek or other local models
- 🔍 Smart Git Analysis: Analyzes commits, file changes, and code diffs
- 🌲 Branch Intelligence: Auto-detects main/master/develop branches
- 📝 Professional Output: Generates structured, readable PR descriptions
- 📋 Custom Templates: Supports GitHub PR templates and custom formats
- 🎯 Context Support: Add custom context and background information to AI prompts
- 🎨 Beautiful CLI: Colored output with progress indicators
- 💾 Export Options: Save to markdown files
- 🌐 Flexible: Works 10000 with any git branching strategy
- Install Ollama:
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve
ollama pull qwen3:latest- Ensure you're in a git repository
Choose your preferred version:
# Install globally
npm install -g prfect
# Or run directly with npx
npx prfect
# Basic usage
prfect
# With options
prfect --source feature/auth --target main --saveEnhance your PR descriptions by providing additional context that may not be visible in the code changes. Perfect for adding ticket numbers, business context, or background information.
# Basic context
prfect "This was a big refactor that addressed Linear ticket BE-123"
# Context with background info
prfect "Fixes critical bug from user reports. Addresses performance issues in checkout flow"
# Context with follow-up information
prfect "Implements OAuth integration per security requirements. Follow up for MFA coming in BE-124"
# Context in CI mode
prfect "Emergency hotfix for production issue" --ci --source hotfix/payment-bug --target main- 📋 Ticket References: Link to Linear, Jira, or other project management tools
- 💼 Business Context: Explain the business reason or user impact
- 🔗 Dependencies: Note related work or follow-up tasks
⚠️ Urgency: Indicate if this is a hotfix or time-sensitive change- 📊 Performance: Provide benchmarks or performance context
- 🔒 Security: Add security considerations or compliance notes
The context is automatically incorporated into:
- Default prompts: Added as "ADDITIONAL CONTEXT" section
- Custom templates: Seamlessly integrated into template-based generation
- CI mode: Included in automated PR generation
- All AI models: Works with any Ollama-compatible model
Prfect supports custom PR templates to match your team's workflow and requirements. It automatically detects and uses GitHub standard templates or allows you to specify custom ones.
- Explicit path:
--template-path custom/template.md - GitHub standard:
.github/pull_request_template.md - Alternative naming:
.github/PULL_REQUEST_TEMPLATE.md - Docs location:
docs/pull_request_template.md - Default built-in: Fallback template
# Use custom template
prfect --template-path .github/custom_template.md
# Auto-detect GitHub template (default behavior)
prfect
# Specify source and target with template
prfect --source feature/auth --target main --template-path team_template.md
# CI mode with custom template
prfect --ci --template-path templates/ci_template.mdTemplates should include common sections that Prfect will intelligently fill:
## Summary
[Brief description of changes]
## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
## Key Changes
-
-
-
## How has this been tested?
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Edge cases considered
## Breaking Changes
[Only include if there are breaking changes]
## Additional Notes
[Any additional information for reviewers]- 🏢 Mono-repo Support: Searches up directory tree for templates
- ✅ Validation: Checks template structure and content quality
- 🔗 GitHub Integration: Works seamlessly with GitHub's PR template system
- 🔄 Fallback Handling: Uses default template if custom one not found
- 🎯 Smart Parsing: AI understands your template structure and fills it appropriately
Create .github/pull_request_template.md:
## Summary
[What does this PR accomplish?]
## Business Impact
[How does this benefit users/business?]
## Technical Details
[Implementation approach and key technical decisions]
## Security Considerations
- [ ] No sensitive data exposed
- [ ] Authentication/authorization reviewed
- [ ] Input validation implemented
## Performance Impact
- [ ] No performance degradation
- [ ] Load testing completed (if applicable)
## Testing Strategy
- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Accessibility tested (if UI changes)
## Deployment Notes
[Any special deployment considerations]
## Documentation
- [ ] README updated (if needed)
- [ ] API docs updated (if needed)
- [ ] Internal docs updated (if needed)Prfect will automatically detect and use this template for all PRs in your repository!
# Generate PR for current branch → auto-detected main
prfect
# Specify source branch
prfect --source feature/authentication
# Specify both branches
prfect --source feature/auth --target main
# Use different AI model
prfect --model llama2
# Save to file automatically
prfect --save
# Custom Ollama host
prfect --ollama-host http://192.168.1.100:11434
# Generate without emojis
prfect --no-emojis
# Show AI thinking process (useful for debugging)
prfect --show-thinking
# Use custom PR template
prfect --template-path .github/custom_template.md
# Add context information to the AI prompt
prfect "This was a big refactor that addressed Linear ticket BE-123. Follow up for BE-124 coming soon but non blocking"
# Context with other options
prfect "Fixes critical bug from user reports" --source feature/bugfix --target main --model qwen3:latestimport { PRGenerator } from "prfect";
const generator = new PRGenerator();
const prMessage = await generator.run({
source: "feature/new-feature",
target: "main",
model: "qwen3:latest",
save: true,
interactive: false,
noEmojis: true,
showThinking: false,
templatePath: ".github/custom_template.md",
context: "This addresses Linear ticket BE-123",
});
console.log(prMessage);{
"scripts": {
"pr": "prfect",
"pr:save": "prfect --save --no-interactive",
"pr:clean": "prfect --no-emojis --save",
"pr:debug": "prfect --show-thinking",
"pr:custom": "prfect --template-path .github/custom_template.md"
}
}Prfect generates professional PR descriptions like this:
# Implement User Authentication System
## Summary
This PR adds a comprehensive user authentication system with JWT tokens,
password hashing, and role-based access control to improve application security.
## Key Changes
- Added JWT authentication middleware with token validation
- Implemented bcrypt password hashing for secure credential storage
- Created user registration and login API endpoints
- Added role-based permission system with admin/user roles
- Updated database schema with users and roles tables
- Added authentication guards for protected routes
## Breaking Changes
- All API endpoints now require authentication headers
- User session handling has changed from cookies to JWT tokens
- Database migration required for new user tables
## Testing Considerations
- Unit tests added for authentication functions
- Integration tests for login/register workflows
- Manual testing required for UI authentication flows
- Load testing recommended for JWT token validationexport OLLAMA_HOST=http://localhost:11434
export PRFECT_MODEL=qwen3:latest
export PRFECT_DEFAULT_TARGET=mainAdd to .git/hooks/pre-push:
#!/bin/sh
if [ "$2" = "origin" ]; then
prfect --save --no-interactive
fi# Global installation
npm install -g prfect
# Local development
git clone <repository>
cd prfect
npm install
npm run build
npm startFeatures:
- ✅ TypeScript support with full type safety
- ✅ Beautiful CLI with colors and progress
- ✅ Programmatic API for integration
- ✅ Professional error handling
- ✅ Interactive and non-interactive modes
- ✅ Comprehensive logging
Prfect works with any Ollama-compatible model:
- qwen3:latest (Default)
- qwen3:0.6b (Good for CI)
- gemma3:latest
- deepseek-coder:latest
- llama3:latest
- codellama:latest
- mistral
- mixtral
For a complete list visit Ollama's model hub and install them with the Ollama CLI.
Install models with:
ollama pull <model-name>The Node.js package supports custom prompt templates:
const generator = new PRGenerator();
generator.setPromptTemplate(`
Custom prompt for ${sourceBranch} → ${targetBranch}
Analysis: ${commitInfo}
Generate: [your requirements]
`);name: Generate PR Description
on:
pull_request:
types: [opened, synchronize]
jobs:
generate-description:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Ollama
run: |
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve &
ollama pull qwen3:latest
- name: Generate PR Description
run: npx prfect --no-interactive --savegenerate-pr:
stage: prepare
script:
- curl -fsSL https://ollama.ai/install.sh | sh
- ollama serve &
- ollama pull qwen3:latest
- npx prfect --no-interactive# Clone repository
git clone <repository>
cd prfect
# Install dependencies
npm install
# Development mode
npm run dev
# Build
npm run build
# Run tests
npm test
# Lint and format
npm run lint
npm run formatprfect/
├── src/
│ └── index.ts # Main TypeScript application
├── scripts/
│ ├── prfect.sh # Bash version
│ └── prfect.py # Python version
├── dist/ # Compiled JavaScript
├── package.json # Node.js configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
"Not in a git repository"
# Ensure you're in a git repository
git status"Ollama is not accessible"
# Check if Ollama is running
curl http://localhost:11434/api/tags
# Start Ollama if not running
ollama serve"Model not found"
# List available models
ollama list
# Install default model
ollama pull qwen3:latest"Could not detect default branch"
# Specify target branch explicitly
prfect --target main"No commits found"
# Check if there are commits between branches
git log --oneline main..feature-branchFor detailed logging:
# Node.js version
DEBUG=prfect* prfect
MIT License - see LICENSE file for details.
- Ollama - Local AI model runner
- DeepSeek Coder - Excellent code-focused language model
- Commander.js - CLI framework
- Chalk - Terminal styling
For support, please open a new issue on the GitHub Issues page.