⭐ Starred — AI-Powered GitHub Stars Organizer

Automatically categorize, organize, and showcase your GitHub starred repositories using AI (Claude, GPT-4, Gemini)

Starred transforms your messy GitHub stars into a beautifully organized, AI-categorized collection. Perfect for developers who star repos and forget about them!

🚀 Quick Start • 📸 Examples • 🤖 AI Providers • 📖 Documentation

🎯 Why Starred?

The Problem: You've starred hundreds of GitHub repositories. Finding that Docker tool or that React library you starred months ago? Nearly impossible.

The Solution: Let AI organize your stars automatically.

| Before Starred | After Starred | |----------------|---------------| | 500+ unorganized stars | Neatly categorized by topic | | "Where's that CLI tool?" | Searchable markdown docs | | Empty profile README | Auto-updated showcase | | Manual GitHub Lists | AI-synced categories |

✨ Key Features

🤖 Multi-AI Support

Use Claude, GPT-4, or Gemini to intelligently categorize repositories based on description, language, topics, and README content.

📝 Markdown Export

Generates a beautiful STARRED_REPOS.md with table of contents, categories, star counts, and descriptions.

👤 Profile README Integration

Automatically updates your GitHub profile README with a curated showcase of your starred repos.

🔄 GitHub Actions Automation

Set it and forget it — runs daily to keep your collection organized as you star new repos.

📊 GitHub Lists Sync

Optionally sync your AI-generated categories to native GitHub Star Lists.

🎨 Fully Customizable

Define your own categories, preferences, and display options.

🚀 Quick Start

Option 1: GitHub Actions (Recommended — 5 minutes)

Fork or use this template
Add secrets in Settings → Secrets → Actions:

| Secret | Required | Get it from | |--------|----------|-------------| | GH_PAT | ✅ | Create PAT with starring:read | | ANTHROPIC_API_KEY | Pick one | Anthropic Console | | OPENAI_API_KEY | Pick one | OpenAI Platform | | GEMINI_API_KEY | Pick one | Google AI Studio (Free!) |
Run the workflow: Actions → Update Starred Repos → Run workflow
Check results in STARRED_REPOS.md ✨

Option 2: Local / CLI Installation

# Install from source
git clone https://github.com/amirhmoradi/starred.git
cd starred
pip install -e ".[all]"

# Set environment variables
export GH_TOKEN="ghp_your_token"
export ANTHROPIC_API_KEY="sk-ant-xxx"  # or OPENAI_API_KEY or GEMINI_API_KEY

# Fetch your stars
starred fetch --username YOUR_USERNAME

# Categorize with AI
starred categorize --preferences "Focus on DevOps, AI tools, and web development"

# See your organized stars!
cat STARRED_REPOS.md

📸 Example Output

STARRED_REPOS.md Preview

# ⭐ My Starred Repositories

**847** repositories organized into **18** categories

## 📑 Table of Contents
- [🤖 AI & Machine Learning](#-ai--machine-learning) (142)
- [🌐 Web Development](#-web-development) (98)
- [⚙️ DevOps & Infrastructure](#-devops--infrastructure) (87)
- [🔧 CLI Tools](#-cli-tools) (64)
...

## 🤖 AI & Machine Learning
*Machine learning frameworks, LLMs, AI tools and utilities*

- [langchain-ai/langchain](https://github.com/langchain-ai/langchain) `Python` ⭐ 95,000 - Build LLM applications
- [openai/whisper](https://github.com/openai/whisper) `Python` ⭐ 72,000 - Speech recognition
- [ggerganov/llama.cpp](https://github.com/ggerganov/llama.cpp) `C++` ⭐ 68,000 - Run LLMs locally
...

Profile README Integration

Your GitHub profile automatically displays:

### 🤖 AI & Machine Learning
- [langchain-ai/langchain](https://github.com/langchain-ai/langchain) `Python` ⭐ 95,000
- [openai/whisper](https://github.com/openai/whisper) `Python` ⭐ 72,000

### ⚙️ DevOps & Infrastructure  
- [docker/compose](https://github.com/docker/compose) `Go` ⭐ 34,000
- [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) `Go` ⭐ 112,000

*[View all 847 repositories →](STARRED_REPOS.md)*

🤖 Supported AI Providers

| Provider | Model | Cost | Speed | Quality | |----------|-------|------|-------|---------| | Anthropic | Claude Sonnet 4 | ~$0.02/run | Fast | ⭐⭐⭐⭐⭐ | | OpenAI | GPT-4o | ~$0.03/run | Fast | ⭐⭐⭐⭐⭐ | | Google | Gemini 2.0 Flash | Free tier! | Very Fast | ⭐⭐⭐⭐ |

The tool auto-detects which provider to use based on available API keys.

# Force a specific provider
starred categorize --provider gemini --model gemini-2.0-flash
starred categorize --provider openai --model gpt-4o-mini
starred categorize --provider anthropic --model claude-sonnet-4-20250514

👤 Profile README Setup

Add placeholder tags to your profile repo (username/username/README.md):

## ⭐ My Starred Repositories

<!-- STARRED_REPOS_START -->
<!-- Auto-generated content will appear here -->
<!-- STARRED_REPOS_END -->

Enable the workflow — the "Update Profile README" action will automatically:
- Update the section between the tags
- Copy the full STARRED_REPOS.md to your profile repo
- Add a link to view all stars

🔄 GitHub Lists Sync (Advanced)

Sync AI categories to native GitHub Star Lists:

⚠️ Requires browser cookie (GitHub has no official API for lists)

# Preview changes
starred sync --cookie "$GH_COOKIE" --dry-run

# Apply changes
starred sync --cookie "$GH_COOKIE"

# Reset and recreate all lists
starred sync --cookie "$GH_COOKIE" --reset

<details> <summary><strong>How to get the cookie</strong></summary>

Go to https://github.com/yourusername?tab=stars
Open DevTools (F12) → Network tab
Refresh the page
Click the first request → Headers
Copy the Cookie value

Note: Cookies expire every ~2 weeks.

</details>

⚙️ Configuration Options

Custom Categories

Create categories.json:

[
  {"name": "🤖 AI & ML", "description": "Machine learning and AI tools"},
  {"name": "🏠 Self-Hosted", "description": "Self-hosted alternatives to SaaS"},
  {"name": "🚀 Starter Kits", "description": "Boilerplates and templates"}
]

starred categorize --categories categories.json

AI Preferences

Guide the AI with natural language:

starred categorize --preferences "
I'm a DevOps engineer focused on Kubernetes.
Create categories for:
- Container orchestration
- CI/CD pipelines
- Monitoring & observability
- Infrastructure as Code
Skip frontend and mobile categories.
"

Environment Variables

# Required
GH_TOKEN=ghp_xxxx              # GitHub Personal Access Token

# LLM Provider (at least one)
ANTHROPIC_API_KEY=sk-ant-xxxx  # Anthropic Claude
OPENAI_API_KEY=sk-xxxx         # OpenAI GPT
GEMINI_API_KEY=xxxx            # Google Gemini (free tier available!)

# Optional
GH_USERNAME=yourusername       # Auto-detected if not set
GH_COOKIE=...                  # For GitHub Lists sync

📖 CLI Reference

starred --help

Commands:
  fetch          Fetch starred repos from GitHub API
  categorize     Categorize repos using AI
  update-readme  Update README with starred repos section
  sync           Sync with GitHub Star Lists
  providers      List available LLM providers

Options:
  --help         Show help message
  --verbose      Enable debug logging

Examples:
  starred fetch --username myuser --with-readme
  starred categorize --provider gemini --preferences "Focus on Python tools"
  starred update-readme --readme ./README.md --include-toc --max-repos 100
  starred sync --cookie "$COOKIE" --dry-run

🆚 Comparison with Alternatives

| Feature | Starred | StarListify | Astral | Manual | |---------|------------|-------------|--------|--------| | AI Categorization | ✅ Multi-provider | ⚠️ Gemini only | ❌ | ❌ | | GitHub Actions | ✅ Full automation | ⚠️ Basic | ❌ | ❌ | | Profile README | ✅ Auto-update | ❌ | ❌ | ✅ | | GitHub Lists | ✅ Sync | ✅ | ❌ | ✅ | | Open Source | ✅ MIT | ✅ MIT | ❌ | — | | Custom Categories | ✅ | ⚠️ | ❌ | ✅ | | Multi-LLM | ✅ Claude/GPT/Gemini | ❌ | ❌ | — |

📊 How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  GitHub Stars   │────▶│   AI Analysis   │────▶│    Markdown     │
│  (API fetch)    │     │ Claude/GPT/     │     │   Generation    │
│                 │     │ Gemini          │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                        ┌───────────────────────────────┼───────────────┐
                        ▼                               ▼               ▼
               ┌─────────────────┐            ┌─────────────────┐  ┌─────────┐
               │ STA

Starred

Install / Use

README