An AI-powered, self-service GitHub analytics generator that creates beautiful "Wrapped" style summaries of your GitHub contributions — with smart AI detection, self-reporting, and interactive exports.
- GitHub OAuth Login - Secure authentication via GitHub with verified username
- User Allowlist - Server-side OpenAI API protection for approved users
- BYOK (Bring Your Own Key) - Non-allowlisted users can provide their own OpenAI API key
- Middleware Protection - All API routes and pages protected at the middleware level
- Automated Repository Fetching - Pulls all your repositories with filtering options
- Detailed Statistics - Commits, LOC (additions/deletions/net), language breakdown
- Commit Author Analysis - Detects Copilot agent commits, bot commits, and co-authored commits
- Contribution Calendar - Fetches real GitHub contribution heatmap data via GraphQL
- Organization Detection - Distinguishes between personal and org repositories
- Repository Summaries - GPT-4o generates insightful project descriptions
- Smart Grouping - AI clusters related repositories by project family/purpose
- Year Narrative - Generates a personalized "year in review" story
- Achievement Detection - Identifies standout accomplishments and milestones
- Featured Projects - Highlights your most impactful work
- Development Mode - Set global preference: AI-assisted, Manual, or Mixed
- Per-Repo AI Flags - Override global setting for individual repositories
- Custom Narratives - Add personal notes/context to any project
- Custom Groups - Create your own groupings with custom icons
- Deployment URLs - Track live project URLs (auto-detected + manual)
- Glassmorphism Design - Modern, animated statistics and cards
- Interactive Wrapped Page - Tabbed interface with Overview, Impact, and Repositories views
- Repository Detail Modals - Deep-dive into any project
- HTML Export - Generate self-contained, interactive HTML files
- Returning User Support - Remembers preferences and previous analyses
- No Permanent Server Storage - All data processed in-memory
- LocalStorage Persistence - Preferences and cached data stay on your device
- User Controls Data - Choose which repos to analyze and what to share
See QUICKSTART.md for detailed setup instructions.
- Node.js 18+ and npm
- GitHub account
- OpenAI API key (for AI summaries) OR be on the allowlist
git clone https://github.com/Dan-Co/2025-githubwrapped.git
cd 2025-githubwrapped
npm install
cp .env.example .env
# Edit .env with your credentials
npm run dev- Login - Authenticate with your GitHub account via OAuth
- Set Development Mode - Choose AI-assisted, Manual, or Mixed development style
- Select Repos - Choose which repositories to analyze (with search/filter)
- AI Analysis - AI fetches stats and generates summaries for each repository
- Self-Report - Add narratives, flag AI usage, assign custom groups
- Generate Wrapped - AI creates groupings, achievements, and year narrative
- Review & Edit - Fine-tune summaries in the interactive wrapped page
- Export - Download as self-contained interactive HTML
- Frontend: Next.js 14 with React 18
- Authentication: NextAuth.js with GitHub OAuth (verified login extraction)
- GitHub API: Octokit REST + GraphQL for contribution calendar
- AI: OpenAI GPT-4o with structured JSON responses
- Styling: CSS Modules with glassmorphism effects
- Persistence: LocalStorage for preferences and cached data
See IMPLEMENTATION_GUIDE.md for detailed architecture documentation.
2025-githubwrapped/
├── app/
│ ├── api/
│ │ ├── auth/[...nextauth]/ # NextAuth OAuth with login extraction
│ │ └── github/
│ │ ├── analyze/ # AI repository analysis (allowlist protected)
│ │ ├── contributions/ # GitHub GraphQL contribution calendar
│ │ ├── group/ # AI grouping & narrative generation
│ │ ├── repositories/ # List user repositories
│ │ └── stats/ # Detailed repo statistics & author analysis
│ ├── dashboard/ # Repository selection & self-reporting UI
│ ├── wrapped/ # Final wrapped display with tabs
│ └── page.tsx # Landing page
├── components/
│ ├── ApiKeyModal.tsx # BYOK API key input with validation
│ └── SessionProvider.tsx # NextAuth session wrapper
├── types/
│ ├── index.ts # Core types (repos, preferences, groups)
│ └── next-auth.d.ts # Extended session types with login
├── utils/
│ ├── preferences.ts # LocalStorage preference management
│ └── export/
│ ├── styles.ts # Export CSS generation
│ ├── templates.ts # HTML template generators
│ └── types.ts # Export data types
├── docs/
│ └── SELF_REPORTING_IMPLEMENTATION_PLAN.md
├── middleware.ts # Auth protection for pages & APIs
└── .env.example # Environment variables template
See .env.example for all required and optional environment variables:
| Variable | Required | Description |
|---|---|---|
GITHUB_CLIENT_ID |
✅ | GitHub OAuth app client ID |
GITHUB_CLIENT_SECRET |
✅ | GitHub OAuth app client secret |
NEXTAUTH_URL |
✅ | Your app URL (http://localhost:3000 for dev) |
NEXTAUTH_SECRET |
✅ | Random secret for JWT signing |
OPENAI_API_KEY |
OpenAI API key (required for allowlisted users) | |
ALLOWED_USERS |
Comma-separated GitHub usernames for server API access |
┌─────────────────────────────────────────────────────────┐
│ Middleware Layer │
│ Protects: /dashboard, /wrapped, /api/github/* │
│ Requires: Valid NextAuth session │
└───────────────────────────┬─────────────────────────────┘
│
┌───────────────────────┼───────────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ GitHub APIs │ │ OpenAI APIs │ │ OpenAI APIs │
│ (stats,repos)│ │ (/analyze) │ │ (/group) │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ ✅ Session │ │ ✅ Session │ │ ✅ Session │
│ │ │ ✅ Allowlist │ │ ✅ Allowlist │
│ │ │ OR BYOK │ │ OR BYOK │
└──────────────┘ └──────────────┘ └──────────────┘
- GitHub username verified from OAuth - Not user-editable display name
- Empty username protection - Explicitly blocked from allowlist
- BYOK validation - User keys validated against OpenAI API before use
This app is designed to deploy to Vercel:
- Push to GitHub
- Import to Vercel
- Add environment variables (including
ALLOWED_USERS) - Update GitHub OAuth callback URL to production URL
- Deploy
See QUICKSTART.md for detailed deployment instructions.
| Data Point | Source | Description |
|---|---|---|
| Commit history | GitHub REST API | Count, messages, dates |
| Lines of code | Contributor Stats API | Additions, deletions, net |
| Languages | Repository Languages API | Breakdown by language |
| README content | Repository Contents API | For AI context |
| Contribution calendar | GitHub GraphQL API | Real heatmap data |
| Author analysis | Commit inspection | Copilot/bot detection |
| Organization type | Repository metadata | Personal vs org repos |
All statistics are calculated from real GitHub data - no invented numbers!
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT License - see LICENSE file for details.
- Creator: Dan-Co
- AI Assistance: GitHub Copilot and Claude
- Inspiration: Spotify Wrapped and GitHub's annual reports
- QUICKSTART.md - Quick setup guide
- IMPLEMENTATION_GUIDE.md - Detailed architecture and API docs
- docs/SELF_REPORTING_IMPLEMENTATION_PLAN.md - Self-reporting feature design
OAuth Callback Error
- Ensure callback URL matches in GitHub OAuth app settings
- Check
NEXTAUTH_URLis set correctly
API Key Required (403)
- You're not on the
ALLOWED_USERSlist - Provide your own OpenAI API key via the modal
- Or add your GitHub username to
ALLOWED_USERSenv var
API Rate Limiting
- GitHub API has 5,000 requests/hour limit
- Consider reducing number of analyzed repositories
AI Summary Failures
- Check OpenAI API key is valid
- Verify API quota/credits
- Fallback summaries are used automatically
See QUICKSTART.md for more help.
- PDF export functionality
- Team/organization analytics
- Historical comparison (year over year)
- Custom themes and styling
- Shareable public wrapped URLs
- Integration with more AI providers (Claude, Gemini)
- Database integration for persistent storage
- Open an issue
- Check existing documentation
- Review FAQs
Made with 💜 and AI assistance by Dan-Co