# GithubStarsManager — Full AI Knowledge Page

> **Purpose:** This is the canonical AI-readable knowledge page for GithubStarsManager. All information here is intended for AI systems (LLM retrieval, RAG grounding, AI search indexing). Last updated: 2026-08-28.
> **Structured Data:** [/api/profile.json](https://gsm.aminta.top/api/profile.json) | [/llms.txt](https://gsm.aminta.top/llms.txt) (shorter overview)

---

## Project Overview

**Name:** GithubStarsManager
**Type:** Open-source desktop/web application
**Tagline:** AI-Powered GitHub Stars, Forks & Gists Manager
**URL:** https://gsm.aminta.top
**Repository:** https://github.com/AmintaCCCP/GithubStarsManager
**Author:** AmintaCCCP (GitHub)
**License:** MIT
**Status:** Active development

### What It Does

GithubStarsManager is a local-first tool that helps developers manage their GitHub starred repositories, forks, and Gists using AI. It solves the common problem of accumulating hundreds or thousands of GitHub stars over time without a way to find or organize them effectively.

The application connects to your GitHub account via personal access token, pulls your starred repository list, forks, and Gists, and uses AI to:
- Generate summaries and descriptions for each repository or Gist
- Extract relevant tags and topics automatically
- Categorize repos into intelligent groups
- Track releases and notify you of updates
- Let you search using natural language or vector semantic search
- Sync forks with upstream and trigger GitHub Actions workflows

### Why It Was Built

Most developers star repositories with the intention of returning to them later. But with hundreds of stars, the GitHub stars page becomes an unmanageable list. GithubStarsManager solves this by building a local, AI-enhanced knowledge base of everything you've starred, forked, or saved as Gists.

### Target Users

- Developers with 100+ GitHub starred repositories
- Technical professionals who research and collect tools, libraries, and resources
- Teams that share and track development tools via GitHub stars and forks
- Open-source maintainers who want to monitor their tool ecosystem
- Developers who manage code snippets via GitHub Gists

---

## Technical Architecture

### Core Technologies

| Layer | Technology | Purpose |
|-------|-----------|---------|
| Frontend | React 18 + TypeScript + Tailwind CSS | UI rendering and state |
| Desktop Runtime | Electron | Cross-platform desktop application |
| Database | SQLite | Local data storage |
| AI Integration | OpenAI / Anthropic / Ollama | LLM-powered analysis |
| Vector Search | Cloudflare Vectorize | Semantic embedding storage & retrieval |
| GitHub API | REST v3 | Repository, fork, and Gist data fetching |

### System Architecture

The application follows a layered architecture:

1. **GitHub API Layer** — Authenticates with GitHub via PAT, fetches starred repos, forked repos, Gists, release data, and trending information.
2. **Data Processing Layer** — Parses repository metadata, handles pagination, manages rate limits, stores data in SQLite.
3. **AI Analysis Layer** — Sends repository or Gist content to configured LLM API for summarization, tag extraction, and categorization.
4. **Vector Search Layer** — Generates embeddings via multiple providers (OpenAI, Gemini, Cohere, Ollama, SiliconFlow) and stores them in Cloudflare Vectorize. Queries use semantic similarity with optional AI reranking.
5. **Sync Layer** — Optional WebDAV sync for cross-device data sharing. Supports both full sync and incremental updates.
6. **UI Layer** (Electron) — Cross-platform desktop interface with search, category browsing, release timeline, fork management, gist editor, and settings.

### Data Storage

All data is stored locally in SQLite by default. No cloud account required. The database contains:
- Starred repository records (name, description, stars, forks, language, topics, AI-generated tags)
- User categories and custom category mappings
- Release history and read/unread status
- Fork records with upstream sync status
- Gist records with AI-generated summaries
- Trending repository cache
- AI model configuration and usage stats

### AI Model Configuration

GithubStarsManager supports three AI modes:

**OpenAI Mode**
- Uses OpenAI's API with user-provided key
- Supports GPT-4o, GPT-4o-mini, and other chat models
- Cost-based billing via OpenAI

**Anthropic Mode**
- Uses Anthropic's Claude API with user-provided key
- Supports Claude 3.5 Sonnet, Claude 3 Opus
- Cost-based billing via Anthropic

**Ollama Mode (Local)**
- Connects to locally running Ollama instance
- Zero API costs — runs entirely on your hardware
- Supports any Ollama-compatible model (Llama, Mistral, Qwen, etc.)
- Recommended for privacy-conscious users or those with GPU hardware

### Privacy Model

The application defaults to 100% local operation:
- GitHub PAT is stored locally and never transmitted except to GitHub API
- AI analysis can be done locally via Ollama or via your own API keys
- No telemetry, no analytics, no third-party services (except optional AI providers)
- WebDAV sync is end-to-end encrypted by the sync provider
- Vector search embeddings are stored in your own Cloudflare Vectorize index

---

## Feature Specifications

### 1. Starred Repository Management

**Import**
- Authenticate with GitHub personal access token (read-only scope)
- Fetch all starred repositories with full metadata
- Support both full sync and incremental sync since last import
- Handle rate limits gracefully with exponential backoff
- Allow abort of long-running sync operations

**Storage**
- SQLite database stored in user's local app data directory
- Each record includes: full name, description, stars, forks, language, topics, homepage URL, default branch, created date, pushed date, AI-generated summary, AI-generated tags, category assignments, unread status

**Updates**
- Incremental sync mode detects new stars, removed stars, and updated metadata
- Background refresh on configurable interval

### 2. AI Smart Analysis

The AI analysis pipeline runs when a repository is first imported or when manual analysis is triggered:

**Content Analysis**
- Reads README.md, package.json, Cargo.toml, go.mod, pyproject.toml, or other language-specific manifest files
- Extracts key functionality, dependencies, use cases, and technical details

**Summary Generation**
- Produces a 2-3 sentence summary of what the repository does
- Written in neutral technical language suitable for search and reference

**Tag Extraction**
- Generates 3-8 relevant tags per repository
- Tags are descriptive (e.g., "CLI", "Web Framework", "Database ORM") not just GitHub topic copy

**Platform Detection**
- Identifies supported platforms: macOS, Windows, Linux, Web, iOS, Android, Browser Extension

### 3. Smart Categorization

**Preset Categories** (14 default):
- Frontend Frameworks
- Backend Frameworks
- Mobile Development
- Desktop Applications
- DevOps & Infrastructure
- Databases & Storage
- AI & Machine Learning
- Developer Tools
- Open-Source Libraries
- Learning Resources
- Productivity Tools
- Security & Privacy
- Data Science
- Other

**Custom Categories**
- Users can create unlimited custom categories
- Each category has a name, icon, and color
- AI suggests category matches based on extracted tags

**Auto-Matching**
- AI compares repository tags against category descriptions
- Generates confidence scores for each potential category match
- User can accept, modify, or reject AI suggestions

### 4. Release Tracking

**Subscription Model**
- Subscribe to any starred repository for release updates
- Per-repo subscription with enable/disable toggle
- Supports repositories not owned by the user

**Timeline View**
- Chronological display of releases across all subscribed repos
- Filter by repository, date range, or release type (major/minor/patch)
- Unread indicator for new releases
- One-click mark-as-read for individual or all releases
- Latest-only mode for focused tracking

**Notifications**
- Desktop notifications for new releases (configurable)
- Platform-specific asset detection (downloads .dmg, .exe, .AppImage matching your OS)
- Direct download links within the application
- Smart asset filters by keywords (dmg / mac / arm64 / aarch64)

**Sync Mechanism**
- Paginated fetching through all pages until reaching last-seen release
- Respects rate limits with configurable wait times
- Supports abort signal to cancel long-running fetches

### 5. Natural Language Search

**Query Types**
- Free-text natural language queries: "show me CLI tools for text processing"
- Tag-based queries: "language:python tags:machine-learning"
- Multi-dimensional filters: stars:>1000 language:Go

**Search Backend**
- SQLite FTS5 (Full-Text Search) for fast local queries
- AI-enhanced re-ranking of results using LLM to assess relevance
- Automatic fallback from vector search to keyword search on failure

**Filter Dimensions**
- Language (programming language)
- Stars (range)
- Forks (range)
- Topics (from GitHub)
- AI-generated tags
- Category
- Has README
- Has releases
- Date range (starred date, pushed date)
- Subscription status

### 6. Vector Semantic Search

**How It Works**
1. Frontend generates embeddings via 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) |

**Configuration**
- Deploy the Cloudflare Worker (see cloudflare-worker/README.md)
- Configure Worker URL and auth token in Settings → Vector Search
- Select embedding provider and model
- Rebuild index to embed and upload all repos

### 7. Fork Management

**Fork Listing**
- Automatically fetches all your forked repos
- Detects upstream changes and shows behind/ahead counts
- Separate personal and organization forks

**Upstream Sync**
- One-click merge upstream changes into any branch
- Conflict handling and status display
- Pulse indicator for forks with new upstream commits

**GitHub Actions**
- View workflow runs directly from fork cards
- Trigger workflow runs without leaving the app
- Status tracking for triggered runs

**Search & Pagination**
- Full-text search across forked repos
- Configurable page sizes

### 8. Gist Management

**Gist Listing**
- Automatically syncs all your Gists and starred Gists
- Category filtering: All / Mine / Starred
- Search & pagination support

**Create & Edit**
- Multi-file Gist editor with syntax-highlighted code blocks
- Supports adding, renaming, and deleting files
- Create public or secret Gists

**AI Analysis**
- One-click AI summarization for Gist content
- Batch analysis with pause/resume support
- Fallback for truncated or API-unavailable Gists

**Semantic Search**
- AI-powered search reranking to find Gists by intent
- Not just filename matching — understands code purpose

**Detail View**
- Expandable Gist detail modal with file content
- Syntax highlighting and copy-to-clipboard
- Star/unstar Gists directly from the card

### 9. Trending Discovery

**Data Source**
- Fetches from GitHub public trending page
- Filters by programming language, date range (daily/weekly/monthly)
- Retrieves trending data with AI summaries

**Five Discovery Channels**
- Trending / Hot Release / Most Popular / Topic / Search

**AI Enhancement**
- Each trending repository gets a one-click AI analysis
- Shows trending reason and context
- Allows one-click subscribe for release tracking

### 10. Network Proxy

**Proxy Support**
- HTTP Proxy with standard CONNECT tunneling and optional authentication
- SOCKS5 Proxy with full support including username/password auth (RFC 1929)
- Protocol-level testing — actual protocol handshakes, not just TCP connect

**Encrypted Storage**
- Proxy passwords encrypted at rest with AES-256-GCM

### 11. Remote Download (aria2 RPC)

Send release download links directly to an aria2 daemon via JSON-RPC. Works in both backend-proxied mode and client-only mode.

### 12. Diagnostic Logs

- Unified frontend/backend log viewer
- Debug capture mode for troubleshooting
- Fork/workflow event types and HTTP detail capture
- Debug indicator navigation

### 13. Features Added in v0.7.5 – v0.7.8 (August 2026)

- **Repository Q&A Assistant (v0.7.8)** — Ask questions about any repository in natural language. An evidence-driven agent progressively retrieves README, commit, and issue evidence (read-only, commit-pinned), gates answers on collected evidence, validates citations, and presents traceable source cards with task-card timelines. Supports retrieval budgets/depth presets and keeps conversation history locally per repository. Designed for simple questions; does not index every repository file.
- **Release Download Sheet (v0.7.8)** — Per-repository "View releases" sheet with theme-aware styling, paginated assets and notes, source ZIP/TAR archives, optional AI summaries, and browser or aria2 RPC downloads.
- **Multi-Theme Presets (v0.7.7)** — 12 built-in themes (Default, Claude, Vercel, T3 Chat, Deep Purple, Zen-inspired, WhatsApp, and more), each with matched light + dark palettes. One-click switching in Settings > General > Appearance with live previews; all colors, radii, shadows, and fonts are design-tokenized so every preset restyles the whole app.
- **GitHub-Style README Rendering (v0.7.6)** — Repository READMEs and release notes render with official GitHub (Primer) styling, including GitHub Alerts callouts, gemoji, KaTeX math, and Mermaid diagrams (lazily loaded); table of contents, side-by-side translation, and copy-code buttons remain compatible.
- **GitHub Lists Sync (v0.7.5, Experimental)** — Two-way synchronization between local categories and GitHub native Lists, with sync modes, list-to-tag/category mapping, and protected categories.
- **Built-in MCP Server** — Local Model Context Protocol server (default `http://127.0.0.1:3927/mcp`, loopback-only, token-protected, Streamable HTTP + SSE endpoints). Tools: `gsm_status` (repo count / vector availability), `gsm_search_repos` (keyword search with language/tag/platform/license/category/star filters and pagination), `gsm_get_repo`, `gsm_list_categories`, `gsm_list_repos_by_category`, `gsm_stats`, and `gsm_vector_search` (semantic search, listed when vector search is configured). Connect Claude Desktop, Cursor, or any MCP client to query the star library as a tool.
- **Full-Stack Docker Image (August 2026)** — Optional all-in-one container bundling frontend + backend for single-container self-hosting, alongside the backend-only image.

### 14. Cross-Platform Support

| Platform | Package Format | Notes |
|----------|---------------|-------|
| Windows | .exe installer | x64 |
| macOS | .dmg (arm64 + Intel) | Apple Silicon and Intel builds |
| Linux | .AppImage | x64 |
| Web | Browser-based client | Self-hosted via Docker |
| Docker | Docker image | Backend-only or all-in-one full-stack image |

---

## Comparative Analysis

### vs. Manual GitHub Stars

GitHub's native stars page is a flat, chronologically sorted list with no search, categorization, or intelligence. GithubStarsManager adds structured organization, AI-powered search, vector semantic search, fork management, Gist management, and proactive release tracking on top of the same data source.

### vs. Raindrop.io / Other Bookmark Managers

Most bookmark managers treat GitHub repositories as generic URLs. GithubStarsManager specifically understands repository structure — it parses READMEs, understands programming languages and frameworks, and generates repository-specific metadata. It also manages forks and Gists, which generic bookmark tools cannot.

### vs. GitHub's Built-in Lists

GitHub lists are manually curated without AI assistance. GithubStarsManager automates categorization through AI analysis and provides natural language and vector semantic search over the entire collection.

---

## Installation Guide

### Prerequisites

- GitHub personal access token (read-only scope: `repo`, `user`, `gist`)
- For AI features: OpenAI API key, Anthropic API key, or Ollama running locally
- For vector search: Cloudflare account with Vectorize enabled
- For desktop: macOS 10.15+, Windows 10+, or Linux with WebKitGTK

### Quick Start

1. Download the latest release for your platform from https://github.com/AmintaCCCP/GithubStarsManager/releases
2. Install and launch the application
3. Enter your GitHub personal access token when prompted
4. The application will begin syncing your starred repositories, forks, and Gists
5. Once sync completes, use the sidebar to browse categories or use the search bar for natural language queries
6. Optionally configure Vector Search in Settings for semantic matching

### Docker Deployment

```bash
docker pull ghcr.io/amintacccp/github-stars-manager-fullstack:latest
docker-compose -f docker-compose.fullstack.yml up -d
```

The optional all-in-one full-stack image serves the web UI and the backend API (including the MCP endpoint) from a single container on port 8080, with data persisted in a Docker volume. A backend-only image (`ghcr.io/amintacccp/github-stars-manager-backend`) is also available; `github-stars-manager-server` remains as a legacy compatibility alias.

### Ollama Setup (Local AI)

```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2

# Ensure Ollama is running
ollama serve

# In GithubStarsManager settings, set AI provider to "Ollama"
# and enter http://localhost:11434 as the endpoint
```

---

## Development & Contributing

**Language:** TypeScript/JavaScript (React UI + Electron), Go (packaging)
**Database:** SQLite with FTS5
**Build:** Vite + Electron builder

To build from source:
```bash
git clone https://github.com/AmintaCCCP/GithubStarsManager
cd GithubStarsManager
npm install
npm run dev
```

Contributions welcome. Please read the contributing guidelines before opening PRs.

---

## Related Resources

- **DeepWiki Documentation:** https://deepwiki.com/AmintaCCCP/GithubStarsManager
- **Zread AI Docs:** https://zread.ai/AmintaCCCP/GithubStarsManager
- **Product Hunt:** https://www.producthunt.com/products/githubstarsmanager
- **Releases:** https://github.com/AmintaCCCP/GithubStarsManager/releases

---

*This document is maintained for AI systems. For human-readable documentation, see the GitHub README and DeepWiki pages linked above.*