GithubStarsManager

Tired of starring everything and finding nothing?

GitHub Stars Manager automatically syncs your starred repos, uses AI to summarize and categorize them, and lets you find anything with semantic search. Track releases, filter assets, and one-click download — smarter than manual tags, simpler than GitHub.

See it

demo.mp4

More views — Discover, Forks, Gists, Settings, MCP

View	Screenshot
Discover / Trending
Fork management
Gist management
Settings
AI models
Network proxy
Vector search
MCP server

✨ Key Features

🤖 AI-managed repositories Your stars stop being a pile and become a library. The app syncs every starred repo, then AI writes summaries, tags, and categories for them — in bulk, with pause/resume, and with locked categories it will never overwrite. Search by intent instead of remembering exact names.	🧠 Vector search — including "find similar repositories" Natural-language search over your stars, powered by Cloudflare Vectorize: repo descriptions (or full READMEs) are embedded and matched by semantic similarity, with optional AI reranking and automatic keyword fallback. And on any repo card, one click of Find similar repositories builds a semantic neighborhood around it — instantly surfacing the starred repos closest to it.
💬 Repository Q&A Assistant Ask simple, focused questions about a single repository right from its card. Every session is pinned to a specific commit, shows the read-only evidence behind each answer with traceable sources, and keeps its history locally. It doesn't index the whole repository — for deep code analysis, use a mature coding agent.	🛰️ MCP Server Agents like Claude Code and Cursor can read and search your AI-enriched stars through the Model Context Protocol — Streamable HTTP or legacy SSE, Bearer-token auth, read-only tools, enabled from Settings with a copyable agent config. No extra install.
📡 Release tracking Subscribe to repositories and watch every new version land in one unified timeline. Filter assets by platform and file type, save custom keyword rules, and download with one click — in the browser or straight into aria2.	Also included Fork sync and GitHub Actions, Gist browse/edit with AI summaries, 12 theme presets, HTTP/SOCKS5 proxy, WebDAV backup, Discover (Trending / Hot Release / Most Popular), diagnostic logs, bilingual wiki jump, and a packaged desktop client.

Everything else

Feature	Description
Auto-sync Stars	Connect your GitHub token to automatically pull all starred repositories
GitHub Lists Sync	Bidirectional sync with native GitHub Lists: pull Lists into tags/categories with auto-lock, push local categories back as GitHub Lists
Semantic Search	Find repos by intent, not exact names
Repository Release Downloads	Open a repository's current releases from its card; browse paginated assets, release notes, source archives, and optional AI summaries, then download in the browser or through a configured RPC downloader
One-click Downloads	Expand release assets and download instantly
Smart Asset Filters	Match assets by keywords (dmg / mac / arm64 / aarch64)
Discovery Center	Browse GitHub Trending, hot releases, and most popular projects
Fork Management	View, sync upstream, and trigger GitHub Actions workflows on forked repos
Gist Management	Browse, create, edit, and delete Gists; AI-powered summaries and semantic search
12 Theme Presets	Switch instantly between 12 built-in palettes, each with coordinated light and dark variants, from Settings with live previews
Network Proxy	HTTP / SOCKS5 proxy with protocol-level connection testing
Remote Download (aria2)	Send release assets to aria2 for download via JSON-RPC
Diagnostic Logs	Unified frontend/backend log viewer with debug capture mode
Bilingual Wiki Jump	Deepwiki (EN) or zread (ZH) based on repository language
Packaged Client	No environment setup required — download and run

Optional Backend Server

Deploy an Express + SQLite backend for:

• Cross-device Sync — Share data between browsers and devices
• CORS-free API Proxying — AI and WebDAV calls route through the server
• Encrypted Token Storage — API keys stored securely, never exposed to browser
• Network Proxy Forwarding — Route all outbound requests (GitHub, AI, WebDAV) through HTTP/SOCKS5 proxy
• RPC Download Proxy — Forward aria2 download requests through the server with encrypted secret storage

---

🔍 Interface notes

1. Repository Management (Stars View)

Features:

• Auto-sync — Connect your GitHub token to automatically pull all starred repos
• AI Batch Analysis — Select multiple repos and use AI to auto-generate descriptions, tags, and categories; supports pause/resume
• Repo Card Display — Shows stars, forks, language, default branch status; supports expanding README preview
• Category Sidebar — Drag to reorder categories, custom category colors, collapse/expand sidebar; supports locking categories to prevent AI overrides
• Bulk Action Toolbar — Bulk categorize to a specified category, bulk restore AI analysis results
• Multi-layout Support — Adapts layout for desktop and tablet
• Subscription Indicators — Shows which repos have Release update subscriptions
• AI Analysis Status — Shows analyzed / not analyzed / analysis failed; filter by analysis status
• Find similar repositories — From any card, jump to a semantic neighborhood of starred repos closest to it (requires Vector Search)

---

2. Repository Q&A Assistant

Ask concise questions about a single repository directly from its card. Each conversation is tied to a specific commit and shows the evidence used to produce the answer.

Features:

• Commit-pinned, read-only evidence — Sources remain tied to the repository revision selected when the conversation starts.
• Traceable answers — Inspect source links and the assistant's retrieval activity alongside each response.
• Local session history — Revisit, search, and manage conversations independently for each repository.
• Configurable retrieval budgets — Control limits for turns, tool calls, document/code reads, and response duration in AI settings.

Early-access notice: This feature is designed for simple repository questions and may fail, return incomplete evidence, or be unable to answer. It does not index every file in the queried repository. For complex, whole-codebase analysis, multi-file reasoning, debugging, or code changes, clone the repository locally and use a mature coding agent.

---

3. Release Timeline (Releases View)

Features:

• Release Subscription Management — Subscribe/unsubscribe to repo releases; supports bulk unsubscribe
• Timeline Display — Lists all new releases in reverse chronological order; shows read/unread status
• Smart Asset Filtering — Filter by platform (macOS / Windows / Linux / ARM); filter by file type (dmg / zip / deb / rpm / apk)
• Custom Filter Rules — Save custom keyword filter rules
• Expand & Download — Expand release assets list, one-click copy download links; shows file size
• Release Details — Displays version number, release name, time since release
• Multi-view Modes — List view / Grid view toggle
• Paginated Loading — Load historical release records page by page
• Refresh Status Indicator — Shows last refresh time

---

4. Discovery Center (Discover View)

Features:

• Five Discovery Channels — Trending / Hot Release / Most Popular / Topic / Search
• Trending Time Range — Three time dimensions: Today / This Week / This Month
• Trending Filtering Rules — Updated within 30 days, 50+ stars, sorted by stars descending
• Platform Filtering — Filter by OS (All / macOS / Windows / Linux / Browser)
• Programming Language Filtering — Filter by language (JavaScript / TypeScript / Python / Go / Rust, etc.)
• AI Repo Analysis — One-click AI analysis for trending repos
• Subscribe to Trending Repos — Add interesting trending repos to subscription list
• Mobile Tab Navigation — Channel switching adapted for mobile devices

Trending data is sourced from GitHub's trending RSS feed, auto-updated every 30 minutes. Perfect for discovering emerging hot projects, tracking tech trends, and finding learning directions.

---

5. Fork Management (Forks View)

Features:

• Fork Listing — Automatically fetches all your forked repos with upstream update detection
• One-click Sync — Merge upstream changes into any branch with conflict handling
• GitHub Actions — View and trigger workflow runs directly from fork cards
• Read/Unread Tracking — Pulse indicator for forks with new upstream commits
• Search & Pagination — Full-text search, configurable page sizes

---

6. Gist Management (Gist View)

Features:

• Gist Listing — Automatically syncs all your Gists and starred Gists with category filtering (All / Mine / Starred)
• Create & Edit — Multi-file Gist editor with syntax-highlighted code blocks; supports adding, renaming, and deleting files
• AI Analysis — One-click AI summarization for Gist content; batch analysis with pause/resume
• Semantic Search — AI-powered search reranking to find Gists by intent, not just filename
• Detail View — Expandable Gist detail modal with file content, syntax highlighting, and copy-to-clipboard
• Star & Unstar — Star/unstar Gists directly from the card
• Smart Filtering — Filter by analysis status, language, and sort by name/date/file count

---

7. Search & Filters

Features:

• Multi-dimensional Search — Keyword search, repo status filter, tag filter, language filter, platform filter
• AI Analysis Status Filter — Analyzed / Not Analyzed / Analysis Failed / Edited
• Release Subscription Filter — Subscribed / Not Subscribed to Release
• Category Status Filter — Category Locked / Not Locked
• Shortcut Keys Support — Displays search shortcut hints
• Search Statistics — Shows result count and filter conditions
• Search Demo Mode — Demonstrates semantic search capabilities

---

8. Settings Panel

Settings Groups:

Group	Features
General	Language toggle (ZH/EN), light/dark mode, and live-preview switching among 12 built-in theme presets
AI Config	Configure OpenAI / Anthropic / Ollama / compatible APIs; supports custom endpoints and keys
WebDAV	Backup config for Jianguoyun, Nextcloud, ownCloud, and standard WebDAV services
Backup	Backup history, manual backup/restore, incremental backup
Backend Server	Connect to self-hosted backend, API key authentication, sync status indicator
Network	HTTP/SOCKS5 proxy config with protocol-level testing; aria2 RPC remote download setup
Category	Category management, category sorting, default category override rules
Data Management	Data import/export, clear local data, reset all data
Vector Search	Configure Cloudflare Vectorize worker, embedding model, index mode (description / README), and manage index rebuild
MCP Server	Enable MCP so agents (Claude Code, Cursor, etc.) can search your AI-enriched stars via Streamable HTTP / SSE with Bearer-token auth

Appearance: Select any of the 12 built-in theme presets in Settings → General → Appearance. Every preset includes coordinated light and dark palettes and applies immediately across the application.

---

9. Custom AI Models

Features:

• Multi AI Provider Support — OpenAI (GPT-3.5/GPT-4), Anthropic (Claude), Ollama (local models), any OpenAI-compatible API
• Custom Endpoints — Supports privately deployed AI services
• Connection Testing — Test API connection after configuration
• AI Model Selection — Choose the specific model to use

🛠 Tech Stack

• Frontend: React 18 + TypeScript + Tailwind CSS
• State Management: Zustand
• Icons: Lucide React + Font Awesome
• Build Tool: Vite
• Deployment: Netlify

👋🏻 How to Use

💻 Desktop Client (Recommended)

You can download desktop client here: https://github.com/AmintaCCCP/GithubStarsManager/releases

🤖 Run With code

1. Download the source code, or clone the repository
2. Navigate to the directory, and open a Terminal window at the downloaded folder.
3. Run npm install to install dependencies and npm run dev to build

Tip

When running the project locally using npm run dev, calls to AI services and WebDAV may fail due to CORS restrictions. To avoid this issue, use the prebuilt client application or build the client yourself. Alternatively, run the backend server (cd server && npm run dev) to proxy API calls and avoid CORS entirely.

🐳 Run With Docker

Pre-built backend and frontend images are available on GHCR — no local build required. Existing Docker users should continue to use the unchanged two-service Compose deployment:

docker pull ghcr.io/amintacccp/github-stars-manager-server:latest
docker pull ghcr.io/amintacccp/github-stars-manager-frontend:latest
docker-compose up -d

An additional optional full-stack image (ghcr.io/amintacccp/github-stars-manager-fullstack) is available for users who prefer one container, one image tag, and one persistent data volume. It serves the same web UI, /api, and MCP endpoints from one origin. Set API_SECRET in a root .env file first; the full-stack Compose file refuses to start a new unauthenticated deployment:

API_SECRET=replace-with-a-long-random-secret
docker compose -f docker-compose.fullstack.yml up -d

This new option does not replace or modify the existing frontend image, backend image, docker-compose.yml, or desktop clients. The canonical role names are -frontend, -backend, and -fullstack; the existing -server backend image remains a compatibility alias for current deployments. Formal vX.Y.Z Docker tags must match the root package.json client version, while latest and sha-* remain development and traceability tags. See DOCKER.md for full-stack deployment, migration, backup, and rollback instructions.

Note

If the package is private, run docker login ghcr.io first (use a PAT with read:packages scope).

See DOCKER.md for detailed instructions. The Docker setup handles CORS properly and allows you to configure any AI or WebDAV service URLs directly in the application.

🖥️ Backend Server (Optional)

The app works fully without a backend (pure frontend, localStorage). An optional Express + SQLite backend adds:

• Cross-device sync: Share data between browsers/devices
• CORS-free proxying: AI and WebDAV calls go through the server, avoiding browser CORS issues
• Token security: API keys stored encrypted on server, never exposed to browser network tab

Quick Start (Docker — recommended)

docker-compose up -d

Frontend on port 8080, backend on port 3000. Data is persisted in a Docker volume. This existing split deployment remains the recommended option when you need to version, operate, or scale the frontend and backend independently; the optional single-container alternative is documented in DOCKER.md.

To customize, create a .env file:

API_SECRET=your-secret
ENCRYPTION_KEY=your-key
BACKEND_IMAGE_TAG=0.8.0   # pin backend image version (default: latest)
FRONTEND_IMAGE_TAG=0.8.0  # pin frontend image version (default: latest)

Backend only (docker run)

# Basic — no auth, port 3000
docker run -d --name github-stars-backend \
  -v github-stars-data:/app/data \
  -p 3000:3000 \
  ghcr.io/amintacccp/github-stars-manager-server:latest

# With custom secret and encryption key
docker run -d --name github-stars-backend \
  -v github-stars-data:/app/data \
  -p 3000:3000 \
  -e API_SECRET="your-secret" \
  -e ENCRYPTION_KEY="your-key" \
  ghcr.io/amintacccp/github-stars-manager-server:latest

Manual Setup

cd server
npm install
npm run dev

Environment Variables

Variable	Required	Description
API_SECRET	No	Bearer token for API authentication. If unset, auth is disabled.
ENCRYPTION_KEY	No	AES-256 key for encrypting stored secrets. Auto-generated if unset.
PORT	No	Server port (default: 3000)

Connecting Frontend to Backend

1. Open Settings panel in the app
2. Find "Backend Server" section
3. Enter API Secret (if configured)
4. Click "Test Connection" — green indicator means connected
5. Use "Sync to Backend" / "Sync from Backend" to transfer data

🤖 AI Service Configuration

The app supports multiple AI providers. Configure yours in the Settings panel:

• OpenAI: GPT-3.5 / GPT-4
• Anthropic: Claude
• Ollama: local models with no API key needed
• Any OpenAI-compatible API: custom endpoint + key

Steps: open Settings, add an AI config, enter your endpoint and key, pick a model, then test the connection.

🌐 Network Proxy Configuration

The app supports routing all outbound requests through a proxy:

• HTTP Proxy — Standard HTTP CONNECT tunneling with optional authentication
• SOCKS5 Proxy — Full SOCKS5 support including username/password auth (RFC 1929)
• Protocol-level Testing — Connection test performs actual protocol handshakes, not just TCP connect
• Encrypted Storage — Proxy passwords are encrypted at rest with AES-256-GCM

Configure in Settings → Network tab (available in Electron client or with backend server).

⬇️ Remote Download (aria2 RPC)

Send release download links directly to an aria2 daemon:

1. Start aria2 with RPC enabled: aria2c --enable-rpc --rpc-listen-port=6800
2. Open Settings → Network → Remote Download
3. Enter host, port, and optional secret
4. Test connection, then save
5. Release asset buttons will now queue downloads to aria2

Works in both backend-proxied mode and client-only mode (direct browser→aria2 connection).

🧠 Vector Semantic Search (Optional)

Vector Semantic Search uses Cloudflare Vectorize to provide high-precision, natural-language search over your starred repositories. Instead of keyword matching, it embeds repo descriptions (or full README content) into vectors and searches by semantic similarity.

How it works:

1. Frontend generates embeddings via your configured provider (OpenAI, Gemini, Cohere, Ollama, SiliconFlow, or any OpenAI-compatible API)
2. A lightweight Cloudflare Worker acts as a pure Vectorize proxy (store / query / delete)
3. On search, the query is embedded and matched against the vector index; results are optionally reranked by your AI service
4. When disabled or on failure, the app automatically falls back to keyword-based AI search

Supported Embedding Providers:

Provider	Models	Dimensions
OpenAI	text-embedding-3-small / large	1536 / 3072
Gemini	text-embedding-004	768
Cohere	embed-multilingual-v3.0	1024
Ollama	nomic-embed-text / bge-m3	768 / 1024
SiliconFlow	BAAI/bge-large-zh-v1.5	1024
OpenAI-compatible	(custom)	(custom)

Quick setup:

1. Deploy the Cloudflare Worker — see cloudflare-worker/README.md for step-by-step deployment instructions
2. In the app: Settings → Vector Search — enter the Worker URL and auth token
3. Configure an embedding provider (API key + model)
4. Click Rebuild Index to embed and upload all repos
5. Use the AI Search button — it will automatically use vector search when enabled

Warning

After changing the embedding model, you must rebuild the index — different models produce incompatible vector dimensions.

Find similar repositories

From any repo card, click Find similar (or Find similar repositories in the card menu) to see which of your stars are semantically closest to it:

• The repo's text is embedded as a query against your vector index, and results are ranked by similarity — the repo itself is excluded
• Matches appear in a dedicated "Similar repositories" view with a banner showing the anchor repo; click Reset (or any category) to return to your previous view
• Requires Vector Semantic Search to be configured and enabled; without it, the action is unavailable

🛰️ MCP Server (Agent access)

Let agents (Claude Code, Cursor, etc.) read your AI-enriched starred repositories — summaries, tags, categories — and search them via the Model Context Protocol.

• Streamable HTTP (preferred): POST /mcp on the app origin (backend/Docker mode) or http://127.0.0.1:3927/mcp (desktop local mode)
• Legacy SSE: /mcp/sse + /mcp/sse/messages (backend), /sse + /messages (desktop) — for older clients
• Bearer-token auth with a stable token (gsm_mcp_...): generated once when enabled, kept across restarts, only changes when you reset it

Enable: Settings → MCP Server → toggle on. The panel shows the endpoint URLs, the token, and a one-click copyable agent config (JSON) for both Streamable HTTP and SSE. No extra install needed.

Tip

The MCP token is separate from the backend API_SECRET. Pure frontend (no backend) hides the MCP settings page; it works with the desktop (Electron) client or a connected backend.

Exposed tools (read-only):

Tool	Description
gsm_status	Server status: repo count, vector availability, version
gsm_search_repos	Keyword search over stars with filters (languages / tags / platforms / licenses / category / stars) and pagination
gsm_get_repo	Fetch one repo by numeric id or owner/repo, with AI-processed fields
gsm_get_repos	Fetch up to 50 repos in input order; preserves duplicates and reports partial not_found entries
gsm_get_repo_evidence	Return deterministic local repository and latest release-cache evidence; missing values stay null
gsm_list_categories	List custom categories
gsm_list_repos_by_category	List repos in a category with pagination
gsm_stats	Aggregate stats (languages, analysis, tags)
gsm_find_similar_repos	Find similar starred repos with the existing vector index; excludes the source repo and is listed only when Vector Search is available
gsm_vector_search	Semantic vector search — listed only when Vector Search is configured and enabled

gsm_vector_search accepts optional languages, tags, platforms, licenses, category, minStars, maxStars, isAnalyzed, and isSubscribed filters. When a filter is supplied, the Worker returns at most 50 semantic candidates and GithubStarsManager applies the filter locally before truncating to topK; this is not an exact filtered topK over the complete vector corpus. With no filter, the existing query behavior is unchanged. Evidence reads the local repository database and cached releases only, never performs unbounded GitHub fan-out, and does not infer missing fields or return adoption decisions.

gsm_status also returns availableTools (the exact names registered for the current configuration) and conditionalTools (the vector-gated names, whether currently available or not). gsm_get_repo_evidence includes evidenceFreshness from stored repository updated_at, analysis timestamps, and cached release published_at; local repository-sync and release-cache update timestamps are returned as null because they are not stored.

Desktop (Electron) notes: binds loopback (127.0.0.1) only — local agents only; host/port adjustable in Settings (default port 3927).

🔄 GitHub Lists Bidirectional Sync

Native GitHub Lists (starred lists) sync both ways, in addition to the classic REST star sync:

• Pull (GitHub → app) — choose Starred repos & lists in Settings → Star Sync (or on first login). Lists are fetched via GraphQL; each list name is applied as a custom tag, and unlocked repos are categorized to the matching category and auto-locked so AI analysis won't reset them.
• Push (app → GitHub) — click Push categories to GitHub lists in Settings → Star Sync. Each local category is written back as a same-named GitHub List (existing lists overwritten, missing lists created private by default); repos join the lists matching their category, and memberships in lists not managed locally are preserved.

Note

Scope is persistent: switch anytime between Starred repos only and Starred repos & lists in Settings → Star Sync.

💾 WebDAV Backup Configuration

Back up and sync your data via any standard WebDAV service:

• Jianguoyun (坚果云): recommended for users in China
• Nextcloud: self-hosted cloud storage
• ownCloud: enterprise-grade option
• Any standard WebDAV server

Steps: open Settings, add a WebDAV config, enter the server URL, username, password, and path, test the connection, then enable auto-backup.

🚀 Deployment

The build output is a static site, so it deploys anywhere static hosting is supported:

• Netlify: connect your fork, set build command npm run build, publish directory dist
• Vercel: same as Netlify — import repo, build runs automatically
• GitHub Pages: push the dist folder to a gh-pages branch
• Cloudflare Pages: connect repo, build command npm run build, output dist
• Self-hosted: serve the dist folder with any HTTP server (nginx, Caddy, etc.)

For Docker deployment see the Backend Server section above.

Who it's for

• Developers with hundreds/thousands of stars
• People who systematically track releases
• "Lazy-efficient" users who don't want manual tagging

Additional Notes

1. The backend is optional but recommended for web deployment. Without it, all data is stored in your browser's localStorage — back up important data regularly.
2. I can't write code, this app is entirely written by the AI, mainly for my personal requirement. If you have a new feature or meet a bug, I can only try to do it, but I can't guarantee it, because it depends on the AI to do it successfully.😹

🤝 Contributing

Contributions are welcome!

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

MIT — see LICENSE for details.

⭐ Support

If you find this project useful, please give it a star!

For questions or suggestions, open an Issue or reach out to the author.

StarMapper

Star History