⚙️ Clutch

AI-Powered Developer Activity & Productivity Dashboard

Clutch — the ultimate developer companion — is an open-source dashboard that connects directly to your GitHub to visualize your coding journey. It tracks commit streaks, identifies activity patterns, and provides AI-powered weekly insights to help you understand your productivity better than ever before.

🌐 Live Demo · 📖 API Docs · 💻 CLI Tool · 🐛 Report Bug · ✨ Request Feature

---

📋 Table of Contents

• 🎯 The Mission
• ✨ Key Features
• 🔬 How It Works
• 🏗️ System Architecture
• 🛠️ Tech Stack
• 🚀 Quick Start
• 📊 API Reference
• 🗂️ Project Structure
• 🤝 Contributing
• 📜 License

---

🎯 The Mission

GitHub tracks your work. Clutch tracks you. Visualize your contribution streaks and longest active periods. Understand your coding patterns with AI-powered weekly summaries. Identify your most productive days and top-performing repositories. Access your stats instantly via the terminal with a dedicated CLI. Showcase your developer identity with a professional public profile. "Clutch isn't just a dashboard; it's a mirror for your developer journey, helping you stay consistent and focused."

---

✨ Key Features

📊 Activity Charts Beautiful, high-fidelity visualizations of your GitHub contributions over the last 30 days using the GraphQL API.	🧠 AI Summaries Weekly insights generated by Llama 3.1 (via Groq) that analyze your commits to provide actionable feedback.	⚡ CLI First A powerful terminal companion (clutch-cli) for instant access to streaks, stats, and insights.
🔥 Streak Tracking Keep the fire alive with precise tracking of your current and all-time longest commit streaks.	🌍 Public Profiles A dedicated, minimalist profile page at /u/username to share your achievements with the world.	🔐 Secure Auth Seamless GitHub OAuth 2.0 integration with JWT-based session management for the web and CLI.

---

🔬 How It Works

flowchart LR
    A["User Login"] --> B["GitHub OAuth"]
    B --> C["Data Sync"]
    C --> D["Analytics Engine"]
    D --> E["Visual Dashboard"]
    
    C --> C1["GraphQL API"]
    C --> C2["REST API"]
    
    D --> D1["Streak Calculator"]
    D --> D2["Language Parser"]
    D --> D3["AI Insights (Groq)"]
    
    E --> E1["Web UI"]
    E --> E2["CLI Tool"]
    
    style A fill:#000,color:#fff
    style B fill:#000,color:#fff
    style C fill:#000,color:#fff
    style C1 fill:#000,color:#fff
    style C2 fill:#000,color:#fff
    style D fill:#000,color:#fff
    style D1 fill:#000,color:#fff
    style D2 fill:#000,color:#fff
    style D3 fill:#000,color:#fff
    style E fill:#000,color:#fff
    style D3 fill:#000,color:#fff
    style E1 fill:#000,color:#fff
    style E2 fill:#000,color:#fff

Loading

---

🏗️ System Architecture

Clutch uses a modern, decoupled architecture designed for speed and reliability.

---

🛠️ Tech Stack

Frontend

Technology	Purpose
	UI Framework with modern hooks
	Lightning-fast build tool
	Utility-first styling
	Data visualization

Backend

Technology	Purpose
	Runtime environment
	High-performance API framework
	SQL Toolkit and ORM
	Local data persistence

External Services

Technology	Purpose
	Data source (GraphQL & REST)
	AI insight generation
	Secure session management

---

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• Node.js 20 or higher
• A GitHub OAuth app
• A Groq API key

1️⃣ Create a GitHub OAuth App

Navigate to GitHub Developer Settings and create a new OAuth app:

• Homepage URL: http://localhost:5173
• Authorization callback: http://localhost:8000/auth/github/callback

Copy the Client ID and Client Secret.

2️⃣ Backend Setup

cd backend

python -m venv venv

source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env

Configure .env:

DATABASE_URL = sqlite:///./clutch.db

SECRET_KEY = your-secret-key

ALGORITHM = HS256

ACCESS_TOKEN_EXPIRE_MINUTES = 10080

GITHUB_CLIENT_ID = your_client_id

GITHUB_CLIENT_SECRET = your_client_secret

GITHUB_REDIRECT_URI = http://localhost:8000/auth/github/callback

GROQ_API_KEY = your_groq_key

FRONTEND_URL = http://localhost:5173

ENVIRONMENT = development

Start the Backend:

uvicorn app.main:app --reload

The backend will run at http://localhost:8000. Documentation is available at http://localhost:8000/docs.

3️⃣ Frontend Setup

cd frontend

npm install

cp .env.example .env

Configure .env:

VITE_API_URL=http://localhost:8000

Start the Frontend:

npm run dev

The frontend will run at http://localhost:5173.

4️⃣ CLI Setup

pip install clutch-cli

Or install locally from source:

cd cli
pip install -e .

Login (fully automatic — no token copy-pasting):

clutch login

Your browser opens, you authorize on GitHub, and the terminal automatically captures the token. Done.

To point the CLI at a local backend instead of the hosted API:

export CLUTCH_API_URL=http://localhost:8000
clutch login

Available Commands:

Command	Description
clutch login	Login via GitHub OAuth (automatic)
clutch logout	Logout and clear credentials
clutch whoami	Show logged-in user
clutch streak	Current and longest commit streak
clutch stats [--days N]	Activity stats for last N days
clutch heatmap [--weeks N]	Contribution heatmap for last N weeks
clutch repos	Most recently active repositories
clutch insight	AI-generated weekly insight
clutch patterns	Coding patterns and habits
clutch status	Login status and API health
clutch --version	Show CLI version

---

📊 API Reference

Method	Endpoint	Description
GET	/auth/github	Start GitHub OAuth flow
GET	/auth/github/callback	Handle OAuth callback
GET	/users/me	Get authenticated user profile
GET	/users/{username}	Get public user profile
GET	/github/activity	Fetch activity for last N days
GET	/github/streak	Calculate current and longest streaks
GET	/github/languages	Retrieve language breakdown
POST	/github/sync	Sync activity data to database
GET	/insights/weekly	Generate AI weekly insights
GET	/insights/patterns	Detect coding patterns

---

🗂️ Project Structure

clutch/
│
├── backend/                        # FastAPI backend service
│   ├── app/
│   │   ├── main.py                 # App entry point, registers all routers
│   │   ├── settings.py             # Environment variables and configuration
│   │   ├── database.py             # SQLAlchemy database connection and session
│   │   ├── dependencies.py         # JWT authentication middleware
│   │   │
│   │   ├── models/                 # Database Schemas
│   │   │   ├── user.py             # User model — stores GitHub profile and tokens
│   │   │   ├── activity.py         # DailyActivity model — stores synced GitHub stats
│   │   │   └── insight.py          # WeeklyInsight model — stores AI generated insights
│   │   │
│   │   ├── routers/                # API Endpoints
│   │   │   ├── auth.py             # GitHub OAuth flow and JWT creation
│   │   │   ├── github.py           # Activity, streak, language and sync endpoints
│   │   │   ├── users.py            # User profile endpoints
│   │   │   └── insights.py         # AI insight and pattern detection endpoints
│   │   │
│   │   └── services/               # Core Logic
│   │       ├── github_service.py   # GitHub GraphQL API calls and data processing
│   │       └── insights_service.py # AI integration and pattern detection
│   │
│   ├── requirements.txt
│   └── .env.example
│
├── frontend/                       # React + TypeScript frontend
│   ├── src/
│   │   ├── main.tsx                # React entry point
│   │   ├── App.tsx                 # Router setup and protected routes
│   │   ├── index.css               # Global styles and design tokens
│   │   │
│   │   ├── context/
│   │   │   └── AuthContext.tsx     # Auth state management and JWT handling
│   │   │
│   │   ├── utils/
│   │   │   └── api.ts              # Axios instance with auth interceptors
│   │   │
│   │   └── pages/                  # Application Views
│   │       ├── Landing.tsx         # Landing page with sign in
│   │       ├── Dashboard.tsx       # Main dashboard with stats and charts
│   │       ├── Profile.tsx         # Public user profile page
│   │       └── AuthCallback.tsx    # Handles GitHub OAuth redirect and token storage
│   │
│   ├── public/
│   │   └── _redirects              # SPA routing config
│   ├── package.json
│   └── .env.example
│
└── cli/                              # Command Line Tool (published as clutch-cli)
    ├── clutch_cli/
    │   ├── __init__.py
    │   ├── main.py                   # CLI entry point using Typer
    │   ├── api.py
    │   ├── config.py                 # Config and token storage
    │   ├── theme.py
    │   │
    │   ├── activity/                 # Activity related commands
    │   │   ├── __init__.py
    │   │   ├── patterns.py
    │   │   ├── stats.py
    │   │   └── streak.py
    │   │
    │   ├── authentication/           # Authentication commands
    │   │   ├── __init__.py
    │   │   ├── login.py
    │   │   ├── logout.py
    │   │   └── whoami.py
    │   │
    │   ├── insights/                 # AI Insights
    │   │   ├── __init__.py
    │   │   └── weekly.py
    │   │
    │   ├── repositories/             # Repository commands
    │   │   ├── __init__.py
    │   │   └── list.py
    │   │
    │   └── system/                   # System commands
    │       ├── __init__.py
    │       └── status.py
    ├── README.md                   # PyPI package description
    └── pyproject.toml              # Modern build config

---

🤝 Contributing

We love contributions! Please see CONTRIBUTING.md for setup instructions.

---

📜 License

This project is licensed under the MIT License.