AI-powered GitHub stars organizer - categorize repos into lists and clean up stale stars
npm install github-star-manager

English | δΈζ
An AI-powered CLI agent for managing your GitHub Stars.
github-star-manager is a command-line star management agent that leverages LLM to semantically understand your starred repositories. It analyzes the purpose and context of each repo, then organizes them into meaningful categories.
- π Smart Analysis - Analyzes language, topics, and activity of all starred repos
- π Semantic Categorization - Creates meaningful Lists using LLM understanding (not keyword matching)
- β Conservative Unstar - Only suggests removing truly deprecated/broken repos
- πΎ Auto Backup - Automatic backup before operations with one-click restore
- π€ Free by Default - Uses free LLM model via OpenRouter
- π Dry Run - Preview mode to see changes without executing
- Runtime: Bun (TypeScript)
- GitHub API: Octokit REST + GraphQL (Lists API)
- AI: OpenRouter API (default: mimo-v2-flash, free)
``bashInstall globally
npm install -g github-star-manager
Usage
`bash
If installed globally
github-star-managerOr with npx
npx github-star-manager
`$3
`bash
Option 1: Environment variables (recommended)
export GITHUB_TOKEN=your_github_token
export OPENROUTER_API_KEY=your_openrouter_key
github-star-managerOption 2: Runtime input
github-star-manager
Enter tokens when prompted
`$3
Select from these modes at startup:
| Mode | Description |
|------|-------------|
| π Analyze and organize | Full analysis and organization workflow |
| π Restore from backup | Restore from a previous backup |
| π Debug mode | Debug mode (processes only 2 batches) |
| ποΈ Dry run | Preview mode (no actual API operations) |
| πποΈ Debug + Dry run | Combined debug and preview mode |
Architecture
`
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β src/cli.ts β
β β β
β StarManagerAgent β
β (Main Orchestrator) β
β ββββββββββββββΌβββββββββββββ β
β β β β β
β GitHubClient RepoAnalyzer BackupManager β
β (API Client) (AI Analysis) (Backup/Restore) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
`Workflow
`
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 1. Select Mode β
β β’ π Analyze and organize stars β
β β’ π Restore from backup β
β β’ π Debug mode / ποΈ Dry run β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 2. Enter Tokens (or read from env) β
β β’ GITHUB_TOKEN β
β β’ OPENROUTER_API_KEY β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 3. Fetch Data (with live progress) β
β β’ Verify user identity and token permissions β
β β’ Fetch all starred repos: Stars: 100... 200... 1574 β
β β’ Fetch existing Lists β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 4. Auto Backup β
β β’ Saves to ~/.github-stars-backup/ β
β β’ Prompts to continue if backup fails β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 5. Review Existing Lists (if any) β
β β’ π View list contents β
β β’ β¨ Keep lists, suggest new β
β β’ π Reorganize - consider merging/restructuring β
β β’ βοΈ Skip - don't modify lists, only unstar β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 6. AI Analysis (with spinner animation) β
β β AI generating category suggestions... β
β β Categories complete (6 lists) β
β β Ή AI classifying (100/1574)... β
β β Classification complete (1574 suggestions) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 7. Display Analysis Summary β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β π Analysis Summary β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β π¦ Total repos: 1574 β
β π Archived: 45 β
β β° Stale (2+ years): 234 β
β π Suggested Lists (6): β
β β’ AI/ML Tools (156 repos) β
β β’ Web Development (289 repos) β
β ... β
β π― Suggested Actions: β
β β Unstar: 5 repos β
β π Categorize: 1200 repos β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 8. Review (can loop multiple times) β
β β’ π Review suggested lists (6) β
β β’ ποΈ Review repos to unstar (5) β
β β’ π Review categorization (1200) β
β β’ β
Done reviewing, generate plan β
β β’ β Exit without changes β
β β
β Each review option supports: β
β β’ Accept all β
β β’ Skip all β
β β’ Review one by one / by list β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 9. Display Execution Plan β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β π Execution Plan β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β π Create lists (6): β
β β’ AI/ML Tools β
β β’ Web Development β
β ... β
β β Add to lists (1200): β
β β’ owner/repo1 β
β ... β
β β Unstar (5): β
β β’ owner/deprecated-repo β
β ... β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β π Full plan: /tmp/plan-xxx.json β
β β
β Options: β
β β’ β
Execute plan β
β β’ β Remove some actions β
β β’ π Regenerate plan β
β β’ β Cancel β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 10. Execute (with live progress) β
β β
β π Creating 6 lists... β
β "AI/ML Tools"... β β
β "Web Development"... β β
β β
β β Adding repos to lists (1200)... β
β Progress: 500/1200 β
β Result: 498 success, 2 skipped, 0 failed β
β β
β β Unstarring 5 repos... β
β Progress: 5/5 β
β Result: 5 success, 0 failed β
β β
β β
Done! β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
`AI Analysis Pipeline
Analysis is divided into two phases:
$3
`
All repos β Stratified sampling (60) β LLM β 5-8 category suggestions
`- Stratified Sampling: Samples by language proportion to ensure diversity
- Semantic Understanding: Analyzes description, topics, and purpose for deep context
- Output: Generates meaningful category names and descriptions
$3
`
All repos β 30 per batch β LLM β Categorize/Unstar/Keep decision
`- Batch Processing: 30 repos per batch to control API calls
- Three Decisions: Assign to a List / Suggest unstar / Keep unchanged
$3
| Task | Model |
|------|-------|
| Category Suggestions |
xiaomi/mimo-v2-flash:free |
| Repo Classification/Unstar | xiaomi/mimo-v2-flash:free |Uses OpenRouter API. Default model is free. Can be changed in
src/analyzer.ts.GitHub Token Permissions
$3
1. Go to https://github.com/settings/tokens?type=beta
2. Click "Generate new token"
3. Configure:
- Token name:
github-stars-manager
- Expiration: Set as needed
- Repository access: Public Repositories (read-only)
- Permissions:| Permission | Access | Purpose |
|------------|--------|---------|
| Starring | Read and write | Read/add/remove stars |
| Metadata | Read-only | Read repo basic info (auto-included) |
> β οΈ Note: GitHub Lists API currently only supports Classic Tokens. Use a Classic Token if you need Lists functionality.
$3
1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Select scopes:
| Scope | Purpose |
|-------|---------|
|
public_repo | Read public repo info |
| read:user | Read user info |
| user | Create/manage Lists (required) |OpenRouter API Key
1. Go to https://openrouter.ai/keys
2. Create an API Key
3. Ensure your account has credits
Backup & Restore
Backups are automatically saved to
~/.github-stars-backup/.Before each execution, a backup is created containing:
- All starred repos
- All Lists and their contents
To restore, select "π Restore from backup" to:
- Re-star deleted repos
- Recreate deleted Lists
Analysis Strategy
$3
- Stratified Sampling: Samples 60 repos proportionally by language
- LLM Semantic Classification: Understands repo purpose and context
- Considers Existing Lists: Can keep, reorganize, or create new categories$3
Only suggests unstar for:
- β Deprecated with recommended alternatives
- β Joke/meme repos
- β Explicitly marked broken/abandoned
- β Outdated personal forksWill NOT suggest unstar for:
- β
Archived but still useful repos
- β
Old but classic stable libraries
- β
Learning resources
- β
High star count (10k+) repos
FAQ
$3
Symptom: "Cannot create lists" or Lists operations fail
Cause: GitHub Lists API currently only supports Classic Token with
user scopeSolution: Use Classic Token with
user permission enabled$3
Symptom: OpenRouter API returns errors
Possible Causes:
- Invalid or expired API Key
- Insufficient account balance
- Model temporarily unavailable
Solution: Check OpenRouter account status and balance
$3
Symptom: Cannot restore some repos
Possible Causes:
- Original repo was deleted
- Repo was renamed or transferred
- Network issues
Solution: Check error logs and manually handle failed repos
Project Structure
`
github-star-manager/
βββ src/
β βββ cli.ts # Entry point
β βββ agent/index.ts # Main orchestrator StarManagerAgent
β βββ github/client.ts # GitHub API wrapper
β βββ analyzer.ts # AI analysis engine
β βββ backup.ts # Backup/restore manager
β βββ spinner.ts # CLI progress animation
β βββ types/index.ts # TypeScript type definitions
βββ package.json
βββ tsconfig.json
βββ .env.example
``MIT