GitHub Helper - AI Project Management System 🤖

Transform your GitHub repositories into an AI-powered project management hub. Solo-dev organization, finally figured out.

✨ What This Actually Does

Stop hunting down project timelines. Stop scrambling for client meeting summaries. This system reads your actual repositories and gives you:

🧠 AI Repository Analysis: Deep understanding of your codebase structure, tech stack, and code quality
📝 Smart Todo Generation: AI creates actionable task lists based on your actual code, not generic templates
📊 Automated Project Recaps: Perfect meeting summaries with real GitHub metrics
💬 Repository Chat: Ask your codebase questions and get intelligent answers
🔗 Full REST API: Integrate with Cursor IDE, Slack, or anywhere else you need project data
🎨 Beautiful UI: Glassmorphic dark theme that doesn't hurt your eyes during late-night coding

🚀 Quick Start (5 Minutes to Running)

1. Clone & Install

git clone https://github.com/mbishopfx/bishoptech-githubhelper.git
cd bishoptech-githubhelper
npm install

2. Get Your API Keys

You'll need these services (all have free tiers):

OpenAI API Key

Go to OpenAI Platform
Create a new API key
Copy it (starts with sk-)

Supabase Setup

Create account at Supabase
Create a new project
Go to Settings → API
Copy your Project URL and anon public key
Go to Settings → API → Service Role keys
Copy your service_role key (keep this secret!)

GitHub Token

Go to GitHub Settings → Personal Access Tokens
Create new token (classic)
Select scopes: repo, read:user, read:org
Copy your token (starts with ghp_ or github_pat_)

3. Environment Setup

# Copy the environment template
cp .env.local.example .env.local

Edit .env.local with your keys:

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-key-here

# Supabase Configuration  
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

# GitHub Integration
GITHUB_TOKEN=your-github-token-here

# App Security (generate a random 32+ character string)
NEXTAUTH_SECRET=your-random-secret-string-here

# Single User Configuration (personalize it!)
SINGLE_USER_EMAIL=[email protected]
SINGLE_USER_GITHUB_USERNAME=your-github-username
SINGLE_USER_NAME=Your Display Name

# API Security (for integrations)
MASTER_API_KEY=gha_your-generated-api-key

4. Database Setup

# Copy the database setup script
# Go to your Supabase project → SQL Editor
# Paste and run the contents of: database/quick-setup.sql

Or run it manually:

Open Supabase SQL Editor
Copy contents from database/quick-setup.sql
Run the script
Verify tables were created in Table Editor

5. Run It!

npm run dev

Open http://localhost:3000 - you should see the GitHub Helper dashboard!

🏗️ Architecture Overview

Backend Power (API Layer)

Next.js 15 API Routes: Rock-solid /api/v1/ endpoints
LangGraph Multi-Agent System: AI agents that specialize in different tasks
GPT-4o Integration: Context-aware AI that actually understands your code
Supabase PostgreSQL: Scalable database with Row Level Security
GitHub API via Octokit: Real-time repository data and analysis
Single-User Auth: Simplified security model for personal/small team use

Frontend Experience

Glassmorphic UI: macOS-inspired dark theme that looks professional
Framer Motion: Smooth animations and micro-interactions
TypeScript: Full type safety across the entire application
Tailwind CSS: Utility-first styling with custom glassmorphic components
Real-time Streaming: AI responses stream in real-time, no loading screens
Mobile Responsive: Works great on phones and tablets

Project Structure

src/
├── app/
│   ├── api/v1/              # Versioned API endpoints
│   │   ├── ai/chat/         # AI chat functionality
│   │   ├── projects/        # Repository management
│   │   ├── todos/           # Task management
│   │   └── recaps/          # Project summaries
│   └── dashboard/           # UI pages
│       ├── chat/            # Chat interface
│       ├── todos/           # Task management
│       └── repositories/    # Repository browser
├── lib/
│   ├── agents/              # AI agent implementations
│   │   ├── graphs/          # LangGraph workflow definitions
│   │   └── tools.ts         # AI tools and functions
│   ├── github.ts            # GitHub API integration
│   └── supabase.ts          # Database client
└── components/ui/           # Reusable UI components

🎯 How to Use It

Import Your Repositories

Navigate to Repositories in the dashboard
Click Import from GitHub
Your repositories will be analyzed automatically
Review the AI-generated insights

Generate Smart Todos

Select any repository
Click Generate Todo List
AI analyzes your code and creates actionable tasks
Tasks are prioritized based on code complexity and dependencies

Create Project Recaps

Go to Recaps section
Select date range and repositories
AI generates meeting-ready summaries with:
- Progress metrics from GitHub
- Recent commits and changes
- Identified issues and recommendations
- Next steps and priorities

Chat With Your Repositories

Open any repository in the Chat interface
Ask questions like:
- "What's the main architecture of this project?"
- "What dependencies need updating?"
- "What would be the best way to add user authentication?"
AI provides context-aware answers based on your actual code

🔗 API Integration

Cursor IDE Integration

Add this to your Cursor rules:

# GitHub Helper API
LLM Integration: https://your-deployment.vercel.app/llm.txt

Example API Calls

// Generate AI todos for any project
const response = await fetch('/api/v1/todos', {
  method: 'POST',
  headers: { 
    'Authorization': 'Bearer gha_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Sprint Planning Tasks',
    ai_generate: true,
    context_prompt: 'Focus on testing and performance improvements'
  })
});

// Get project recap
const recap = await fetch('/api/v1/recaps', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer gha_your_api_key' },
  body: JSON.stringify({
    period: 'weekly',
    include_metrics: true
  })
});

🚀 Deployment (Production Ready)

Vercel Deployment (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel --prod

Environment Variables for Production

Add these in your Vercel dashboard:

NODE_ENV=production
OPENAI_API_KEY=your_production_openai_key
NEXT_PUBLIC_SUPABASE_URL=your_production_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_production_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_production_service_key
GITHUB_TOKEN=your_production_github_token
NEXTAUTH_SECRET=your_production_secret_minimum_32_chars
[email protected]
SINGLE_USER_GITHUB_USERNAME=your-github-username
SINGLE_USER_NAME=Your Display Name
MASTER_API_KEY=gha_your_production_api_key

🔧 Customization

Modify AI Behavior

Edit src/lib/agents/config.ts:

export const AI_CONFIG = {
  model: 'gpt-4o',  // Change AI model
  temperature: 0.7,  // Adjust creativity (0.0-1.0)
  maxTokens: 2000,   // Response length limit
};

Custom UI Theme

Modify tailwind.config.ts and src/app/globals.css for your branding.

Add New AI Agents

Create new graphs in src/lib/agents/graphs/ using the LangGraph framework.

🐛 Troubleshooting

Common Issues

"Can't connect to Supabase"

Verify your NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
Make sure you ran the database setup script
Check that your Supabase project is active (not paused)

"GitHub API rate limit exceeded"

Your GITHUB_TOKEN might be invalid or expired
Create a new token with proper scopes: repo, read:user, read:org
GitHub has rate limits - wait an hour or upgrade to GitHub Pro

"OpenAI API errors"

Check your OPENAI_API_KEY is correct (starts with sk-)
Verify you have credits in your OpenAI account
Some features require GPT-4 access

"Database errors"

Run database/quick-setup.sql again in Supabase SQL Editor
Check that all tables were created in your Supabase Table Editor
Verify your SUPABASE_SERVICE_ROLE_KEY has full database access

Getting Help

If you're stuck:

Check the Issues tab for similar problems
Create a new issue with:
- Your operating system
- Node.js version (node --version)
- Error message (remove any API keys!)
- Steps you've tried

📄 License

MIT License - feel free to fork, modify, and use in your own projects!

🙏 Built With

Next.js 15 - React framework
OpenAI GPT-4o - AI language model
LangGraph - Multi-agent AI workflows
Supabase - PostgreSQL database and auth
Tailwind CSS - Utility-first CSS framework
Framer Motion - Animation library
GitHub API - Repository data access

Built with ❤️ for developers who want to stay organized without the overhead

⭐ Star this repo if it helps you get organized!

🐛 Found a bug? Report it here

FilesExpand file tree

README.md

Latest commit

History