Organize, search, and ask questions across your GitHub Stars — locally on your Mac.
macOS 15 Sequoia or newer: Install with Homebrew, download the Direct build for Apple Silicon Macs, or get Starcat for GitHub from the Mac App Store.
Previous versions and release notes: Changelog · Website changelog
Public issue tracker: Report a bug or request a feature
User docs: starcat.mintlify.app · Mac App Store: dong4j.app/starcat · Privacy: Privacy Policy · EULA
中文说明: README-ZH.md
This repository is the macOS app source. Public support, issues, and release notes live in starcat-pro. Docs, CLI, plugins, and self-hostable APIs are listed under Related projects.
Starcat is a native macOS app for people whose GitHub Stars have outgrown a bookmark list. It syncs starred repositories into a local-first desktop workspace, renders README content, adds tags, notes and reading status, tracks releases, evaluates repository health, and turns the repos you still need into a searchable, askable knowledge base.
While building Starcat I started thinking about what a GitHub Star is. We treat them as read-later bookmarks. Over time they become a digital asset: a record of professional interest, technical judgment, and projects we may still need.
A public Star is still an endorsement. Repositories you plan to learn, use, or keep go into the Starcat knowledge base. Starring does not create a backlog you must tidy. Only ingested repos enter search, summaries, and RAG.
Starcat began as a paid product, but the market for deeply managing GitHub Stars proved smaller than expected. Opening the ecosystem makes it easier for the people who need it to inspect, extend, and self-host it. The related projects are now open source, except starcat-license-api, which stays private because it issues Direct licenses. Official Mac App Store and Direct (starcat.ink) builds remain available and will keep being maintained.
starcat-global-search.mp4
starcat-knowledge-rag.mp4
starcat-ai-assistant.mp4
Official channels are the Mac App Store (Starcat for GitHub, landing page dong4j.app/starcat) and Direct (website DMG / Homebrew with Sparkle). Core organization features are free. Pro workflows, higher AI quotas, and code-intelligence features in official builds use App Store in-app purchase or a Direct license.
Building from this repository and running your own services does not require a Starcat license. Direct license issuance stays on the private starcat-license-api.
Homebrew is the preferred install:
brew tap starcat-app/starcat
brew trust starcat-app/starcat
brew install --cask starcatYou can also download the Direct .dmg from starcat.ink, move Starcat to /Applications, and sign in with GitHub.
The main window is a three-column workspace: sidebar, repository list, and the current repo. Two more windows sit beside it: the knowledge-base RAG workspace and the Agent workspace.
Sign in with GitHub OAuth, sync starred repos incrementally, and keep the cache in local SQLite. Repository cache can be rebuilt. Tags, private notes, and reading status are user data and must not be lost.
- Three-column layout, with Liquid Glass on macOS 26
- Tags, languages, untagged, Smart Collections, pinning
- Reading status: Unread / Reading / Adopted / Deprecated
- Private notes, with optional AI drafts from the README
- FTS5 search across names, descriptions, topics, and notes
- Semantic search by intent, not only exact keywords
- README rendering with images, Mermaid, and a reading surface
- JSON import and export compatible with OhMyStar and Astral
Activity is the in-app inbox for GitHub mentions, review requests, assignments, discussions, releases, and security alerts. Filter by Unread, Mentions, Reviews, Issues, and PRs; group by Today, Yesterday, This week, and Earlier.
Open a notification to read the Issue or PR thread, write or preview a reply, generate an AI draft, and translate comments. Done matches GitHub Inbox Done and does not close the issue. Starcat can also post reminders in Notification Center.
Stars and the knowledge base are separate layers. A GitHub Star is a public endorsement. The knowledge base is your private set of repos worth keeping. You can ingest from Stars in bulk, or add a repo from Explore, Weekly, or Trending without starring it on GitHub first.
RAG indexing, knowledge-base browsing, and the default CLI / MCP context all start from ingested repos. Stars you never ingest stay a collection.
Opens in its own window (⇧⌘K). Questions default to ingested repos. Answers stream with citations you can open back to the matching repository and evidence chunk.
The layout is a conversation rail, an answer surface, and a Citation Inspector. Retrieval mixes FTS5 keywords, embeddings, and RRF. The index is chunk-level, so a citation can point at a paragraph, not only a repo name.
You can attach insight XML, README / notes / summary chunks, and text, Markdown, JSON, or source-code files. GitHub structured lookups and web search are opt-in, and they show up on the execution timeline. The workspace is read-only by default. It will not write tags, notes, or library state on its own.
- Repo Health: activity, maintenance, risk signals
- OpenSSF Scorecard: public security radar
- My Insights: organization progress, tech mix, follow-ups
- Repository Insights: star growth, commits, collaboration, release cadence, health and security
- Generated insights can feed summaries, repo chat, and RAG as removable read-only context
Smart Collections cover Needs Review, Unmaintained, High Value, No Tags, and custom rules over metadata, status, notes, and Health. My Projects lists personal, organization, and collaborator repos, including private ones via GitHub App.
Explore covers GitHub Trending, discovery boards, and sources such as ruanyf Weekly, plus Release subscriptions, a unified timeline, and platform-filtered assets. Desktop widgets surface frequent repos, a daily rediscovery, unread releases, and star trends.
From the repo detail you can copy the GitHub link for people who do not have Starcat. Starred public repos can also get a standalone public share page: summary, stars / forks, README highlights, topics, and switchable card styles. Recipients open a webpage. No account required.
Public share pages run on starcat-sharing-api, which you can self-host. Private repos do not get a page the server can crawl.
You can pull the current repo's source onto this Mac and inspect structure without cloning it into another IDE. Starcat embeds two open-source analyzers:
- codebase-memory-mcp: a symbol-level knowledge graph. Files, classes, functions, and dependencies unfold in a local 3D view, filterable by type.
- codeflow: an architecture checkup. File size, coupling, cycles, duplication, complexity, and a health score.
Source defaults to a GitHub ZIP. Generated artifacts can be deleted.
This is AI in the main-window detail pane, not a separate workspace. Notes, summaries, and tags stay on this Mac. After ingest they enter RAG.
- Notes: AI can draft a private note from the README. You edit it afterwards. This is where gotchas, setup steps, and mismatches with upstream docs belong. Notes never go back to GitHub.
- Summaries and tags: AI reads the README and writes a structured summary (what it does, which stack, where it fits), then suggests tags. Tags land only after you confirm. You can also batch-generate tags for every starred repo and confirm them one by one. Both summaries and tags are indexed for RAG.
- Repo chat: Ask the current project directly, for example how to build it or where a feature lives. Answers use that repo's README, notes, and summary. You can also translate the README while keeping structure, as a bilingual view or a full replacement.
CLI, MCP, an Agent Skill, browser plugins, and launchers all read the local store. The browser plugins bring notes, tags, health, and AI actions onto GitHub pages. Alfred, uTools, and Raycast search local repos. Share cards and short links work for people who do not have Starcat installed.
AI runs through BYOK or a self-hosted proxy: Gemini, OpenAI, Anthropic Claude, DeepSeek, Ollama. Keys and quotas stay with you. The UI ships in 18 languages. Translations live in starcat-localization.
Tags, private notes, reading status, knowledge-base membership, and RAG chunks stay in local SQLite. GitHub tokens and AI API keys stay in Keychain. Repository cache (README, metadata) can be rebuilt. User data cannot.
Traffic that leaves the Mac:
- GitHub.com: Stars sync, README / Release fetch, OAuth
- The AI provider you configure: summaries, chat, RAG generation, and embeddings (Ollama stays on-device)
- Optional Starcat support APIs: Trending, Weekly, discovery, wiki probes, similar-repo recommendations, public share pages. All of these can be self-hosted
- Optional external search backends: Meilisearch and Qdrant. The default remains SQLite FTS5 and local vectors
CloudKit sync fields are reserved. The production adapter is not wired yet. Starcat does not host your AI keys, and it does not upload the knowledge base to a Starcat server by default.
This repository is the macOS app. Starcat also has standalone repos for docs, distribution, CLI, plugins, and self-hostable APIs. The full map is in supports/README.md. Organization home: github.com/starcat-app.
| Project | Role |
|---|---|
| starcat.ink | Direct website, downloads, release notes |
| dong4j.app/starcat | Mac App Store landing page |
| starcat-pro | Public support, issues, changelog, and promo images |
| starcat-docs | Official user docs, published at starcat.mintlify.app |
| starcat-site | Direct / App Store site and legal pages |
| starcat-localization | UI localization, currently 18 languages |
| homebrew-starcat | App Homebrew Cask: brew install --cask starcat |
| Project | Role |
|---|---|
| starcat-cli | Cross-platform CLI and MCP runtime over the local knowledge base |
| homebrew-starcat-cli | CLI Homebrew Formula |
| starcat-skill | Skill for agents such as Codex and Claude Code |
| starcat-chrome-plugin | Chrome extension with Starcat context on GitHub pages |
| starcat-safari-plugin | Safari extension |
| starcat-alfred-workflow | Search local repos and GitHub from Alfred |
| starcat-utools-plugin | Search local repos and GitHub from uTools |
| starcat-raycast-extension | Search local repos and GitHub from Raycast |
The app talks to a small set of independent APIs. GitHub has no Trending endpoint. Weekly, discovery, wiki probes, similar-repo recommendations, and public share pages also need a server. These repos can be deployed on your own. Each one has its own README and deploy notes.
| Project | Role |
|---|---|
| starcat-sharing-api | Share short links and public share pages |
| starcat-trending-api | GitHub Trending crawl and API |
| starcat-weekly-api | Weekly, Show HN, HelloGitHub, and related feeds |
| starcat-wiki-api | DeepWiki / Zread / CodeWiki availability |
| starcat-recommend-api | Similar-repository recommendations |
| starcat-discovery-api | Explore, popular, and new-release boards |
| starcat-api-kit | Shared auth, envelope, and GitHub helpers |
| starcat-license-api | Direct licensing, private repository |
Knowledge-base keywords default to SQLite FTS5. Vectors default to local cosine. To try the optional external backends on this Mac, see docker/meilisearch and docker/qdrant. Bind them to 127.0.0.1 only.
- SSPAI: 我为 GitHub 重度使用者做了一款 macOS 原生应用
- Blog: the same essay
The full walkthrough (macOS app, support APIs, CLI, local Meilisearch / Qdrant) is 本地编译教程 (Chinese). Contributor rules: CONTRIBUTING.md.
Short path: macOS 15+, Xcode 26+, brew install xcodegen, checkout dev, copy Configs/Secrets.xcconfig.template, run xcodegen generate, then Run the Starcat scheme. After adding or deleting Swift files, generate the project again.
Clone the supporting repos in one pass:
cd supports
./clone-all.shsupports/ is a workspace of independent git repos. Those trees are not committed here. starcat-license-api and starcat-api are private and need org access.
Starcat/
├── App/ # Entry, lifecycle, dependency composition
├── Features/
│ ├── Home/ # Three-column main window
│ ├── RAG/ # Knowledge-base RAG workspace
│ ├── Agents/ # Agent workspace
│ ├── AI/ # Summaries, chat, translation, semantic search
│ ├── Insights/ # Library and repository insights
│ ├── Explore/ # Discovery
│ ├── Trending/ # GitHub Trending
│ ├── Tags/ # Tags
│ ├── Releases/ # Release subscriptions and timeline
│ ├── MCP/ # Local MCP facade
│ └── Settings/ # Settings
├── Core/
│ ├── Database/ # GRDB / migrations
│ ├── RAG/ # Chunk index and writes
│ ├── Network/ # GitHub API
│ ├── Sync/ # Stars sync
│ └── Keychain/ # Tokens and API keys
├── Shared/ # Shared components and utilities
└── Resources/
Quit Xcode before command-line tests, or the two will fight over testmanagerd. Any start-up path that talks to Keychain or system authorization must be gated with TestEnvironment.isRunning, or the test host hangs.
xcodegen generate
xcodebuild -scheme Starcat -destination 'platform=macOS,arch=arm64' test| Layer | Technology |
|---|---|
| Client | SwiftUI on macOS 15+, Liquid Glass on macOS 26 |
| Local database | GRDB.swift (SQLite), FTS5, local embeddings |
| Cloud sync | CloudKit fields are reserved, production adapter not wired yet |
| Secure storage | Keychain |
| AI | BYOK / self-hosted proxy (Gemini / OpenAI / Claude / DeepSeek / Ollama) |
- Starcat currently supports macOS 15 Sequoia or newer
- The public Direct download is for Apple Silicon Macs
- There are no iOS, iPadOS, watchOS, Windows, or Android builds
- Building from source needs Apple Developer Program membership ($99/year)
- AI features depend on the provider or API key you configure
| App | Highlights |
|---|---|
| Starship | Nested tags and iCloud sync |
| OhMyStar | Comprehensive features and powerful search |
| GithubStarsManager | AI summaries, semantic search, and release tracking |
- Local build guide - compile the app, support APIs, and CLI (Chinese)
- User docs - install, features, daily use
- Feature list - complete feature specification
- Implementation overview - primary progress index and engineering debt
- Detailed design index - technical design documentation
- DESIGN.md - UI contract for the main window, RAG, and Agent
See CONTRIBUTING.md. Please follow the Code of Conduct.
Report vulnerabilities privately as described in SECURITY.md.
Product questions: starcat-pro. Source-code issues: this repository. Details in SUPPORT.md.
Starcat is built on open-source work. The in-app About → Credits list is the canonical registry (Starcat/Features/About/AboutView.swift). License texts for bundled files are in THIRD_PARTY_NOTICES.md.
Starcat's own CLI, plugins, and APIs are listed under Related projects, not repeated here.
| Project | License | Role |
|---|---|---|
| GRDB.swift | MIT | Local SQLite |
| KeychainAccess | MIT | Token and API key storage |
| Kingfisher | MIT | Image loading and cache |
| swift-markdown-ui | MIT | SwiftUI Markdown for AI summaries |
| OpenAI | MIT | OpenAI-compatible client |
| ConfettiSwiftUI | MIT | Celebration effects |
| ZIPFoundation | MIT | GitHub source ZIP extraction |
| MCP Swift SDK | Apache-2.0 / MIT | Local MCP |
| Aptabase Swift | MIT | Optional analytics |
| Sparkle | MIT | Direct-channel updates only |
| Project | License | Role |
|---|---|---|
| Devicon | MIT | Language / tool icons |
| GitHub Linguist | MIT | Language colors and names |
| Mermaid | MIT | README diagrams |
| CodeFlow | MIT | In-app architecture view |
| codebase-memory-mcp | MIT | Symbol graph and 3D explorer |
| Repomix | MIT | Repository context packing |
| OpenSSF Scorecard | CDLA-2.0 / Apache-2.0 | Security radar |
These are not SPM packages. Starcat uses them through support APIs or as public datasets.
| Project | License | Role |
|---|---|---|
| SimRepo | MIT / GPL-3.0 | Similar-repository recommendations via starcat-recommend-api |
| ruanyf/weekly | CC BY-NC-SA 4.0 | Weekly discovery source |
| HelloGitHub | — | Weekly / discovery source |
The vendored CodeFlow page also loads these libraries:
React, ReactDOM, Babel Standalone, D3, d3-sankey, Acorn, jsrsasign, JSZip, jsPDF, web-tree-sitter, 3d-force-graph.
MIT © 2026 dong4j
Third-party notices: THIRD_PARTY_NOTICES.md
This project has been linked and endorsed by LINUX DO Community.