Your GitHub year in review, beautifully visualized in your terminal
Quick Start • Features • Demo • Token Setup • Contributing
Interactive terminal experience - from stats loading to image export
No installation required. Run it instantly:
# With Bun (recommended - fastest)
bunx gh-wrapped-2025
# With npm
npx gh-wrapped-2025Usage:
- Enter your GitHub username
- Watch your stats load in real-time
- Navigate with arrow keys / spacebar
- Press
[E]to export as image
Note: Most users don't need a token. The app will only prompt you if you hit GitHub's rate limit (60 requests/hour).
- Total commits, PRs, issues, and code changes
- Contribution streaks (current & longest)
- Peak productivity hours
- Most active repository
- Top 5 programming languages
- Usage percentages and visual breakdown
- Language-based statistics
- Archetype Classification: Night Owl, Early Bird, Weekend Warrior, etc.
- Achievement System: Unlock badges based on your activity
- Smart Insights: AI-generated observations about your coding patterns
- Generate beautiful PNG images
- Optimized for social media sharing
- Background Chromium installation (seamless first-time setup)
- 100% Local Processing - No data sent to external servers
- Optimized API Calls - Efficient GraphQL queries with caching
- Optional Authentication - Works without a token for most users
bunx gh-wrapped-2025No installation needed! Just run it once and the app handles everything.
npx gh-wrapped-2025# With Bun
bun install -g gh-wrapped-2025
github-wrapped
# With npm
npm install -g gh-wrapped-2025
github-wrappedgit clone https://github.com/d3varaja/gh-wrapped-cli.git
cd gh-wrapped-cli
# Install dependencies
bun install # or npm install
# Build the project
bun run build # or npm run build
# Run the built version (use Node, not Bun - see note below)
npm start
# or
node dist/index.jsnpm start or node dist/index.js), not bun start. The image export feature uses Playwright which has known compatibility issues with Bun's runtime, especially on Windows. Bun is great for development and building, but Node is required for running the final output.
- Fetches your public GitHub data via GitHub API
- Analyzes commits, repositories, languages, and contribution patterns
- Calculates streaks, peak hours, and determines your developer archetype
- Displays results in a beautiful terminal interface
- Optionally exports to a shareable image
| Package | Purpose |
|---|---|
| TypeScript | Type-safe development |
| React + Ink | Terminal UI framework |
| Octokit GraphQL | GitHub API client |
| Playwright | Headless browser for image generation |
| Bun/Node.js | Runtime environments |
- Bun >= 1.0.0 (recommended) OR Node.js >= 18
- For Bun installation:
curl -fsSL https://bun.sh/install | bash(macOS/Linux) orpowershell -c "irm bun.sh/install.ps1 | iex"(Windows)
# With Bun (recommended)
bun install
# Or with npm
npm install# With Bun (recommended - hot reload)
bun run dev
# Or with npm
npm run dev# With Bun (recommended - faster)
bun run build
# Or with npm
npm run build# IMPORTANT: Use Node, not Bun (Playwright compatibility)
npm start
# or
node dist/index.jssrc/
├── index.tsx # Main CLI entry point
├── github-graphql.ts # GitHub GraphQL API client
├── analytics.ts # Stats calculation & insights
├── ui.tsx # Terminal UI components
├── export-playwright.ts # PNG export with Playwright
├── tier-calculator.ts # Scoring and tier system
├── types.ts # TypeScript type definitions
└── utils/
├── avatar-fetcher.ts # Avatar download utility
├── browser-installer.ts # Background Chromium setup
└── html-injector.ts # Template data injection
You can also use this as a library:
import { GitHubGraphQLClient } from 'gh-wrapped-2025';
const client = new GitHubGraphQLClient('username', 'optional_token');
const user = await client.getUser();
const repos = await client.getRepositories();
const commits = await client.getCommitsForYear(2025);
const languages = await client.getLanguages();GitHub API has rate limits:
- Without token: 60 requests/hour (you'll likely hit this)
- With token: 5,000 requests/hour
The app handles this for you! When you hit the rate limit:
⚠ GitHub API Rate Limit Exceeded
Get a token at: https://github.com/settings/tokens
Paste your GitHub token (or press Ctrl+C to exit): _
That's it! Just paste your token and the app continues.
- ✓ Valid token? → App continues with your data
- ✗ Invalid token? → Shows error, lets you try again
- Ctrl+C → Exit anytime
- Visit: https://github.com/settings/tokens
- Click "Generate new token (classic)"
- Give it a name (e.g., "GitHub Wrapped")
- Leave all scopes unchecked - No permissions needed for public data
- Click "Generate token" at the bottom
- Copy the token
- Paste it when the app asks
Security Note: A token with no scopes can only read public data - it's completely safe and cannot modify anything.
If you're developing or running this locally, you can set a token beforehand:
# Environment variable (one-time)
GITHUB_TOKEN=your_token npx gh-wrapped-2025
# Or create .env file in project directory
echo "GITHUB_TOKEN=your_token" > .envFor most users: just let the app prompt you!
This project is optimized for performance:
- Efficient API Usage: Single GraphQL query with caching (vs multiple REST calls)
- Smart Rate Limiting: Fetches only top 10 repositories (adjustable)
- Background Processing: Chromium installs silently while you browse stats
- Async I/O: Non-blocking file operations
- Type Safety: 100% TypeScript with strict type checking
- Small Bundle: ~800KB minified (externalized dependencies)
Contributions are welcome! To contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and build (
bun run build && bun run build:types) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure:
- Code follows existing style and conventions
- TypeScript compiles without errors
- No breaking changes without discussion
MIT License - see LICENSE file for details
d3varaja
- GitHub: @d3varaja