GithubStarsManager

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

https://github.com/user-attachments/assets/ad3493a0-948a-4de5-8de1-4e9afc46ec4d

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

Everything else

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:

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

🌍 Interface Languages

The UI ships in 10 languages: 简体中文 · English · 日本語 · Español · Português (Brasil) · Русский · 繁體中文 · Français · Deutsch · 한국어.

• Switch anytime in Settings → General → Language, or via the language picker on the login screen; the choice is persisted per browser and the desktop client follows it too.
• First launch picks up your browser/OS language automatically.
• AI-generated content follows the UI language: repository summaries & tags, Gist summaries, Release changelog digests, and Repository Q&A answers are written in the selected language (built-in prompts; a custom prompt keeps full user control).
• Built-in categories follow the UI language as well — display names, AI tag matching, and GitHub Lists syncing all rename automatically when you switch languages.
• Missing translations gracefully fall back to English. Translation drafts are machine-assisted and get refined over time — PRs for translation improvements are very welcome (src/locales).

🛠 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

🐳 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.

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.4   # pin backend image version (default: latest)
FRONTEND_IMAGE_TAG=0.8.4  # 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

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:

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

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.

Exposed tools (read-only):

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).

🔌 Local plugins (desktop)

The Electron app can load trusted local plugins from a directory. They stay disabled until you grant the permissions in their Manifest. Worker plugins run as isolated Node.js (not a security sandbox); page plugins run in a restricted iframe.

• Plugin usage — install, enable, permissions, where actions appear
• Plugin development — Manifest, Worker API, page bridge, limits
• Examples: examples/plugins/

Enable: Settings → Plugins → Install local plugin. Browser and Docker frontend builds do not include this host.

🔄 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.

💾 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