⭐ StarMagpie

A native macOS app for turning GitHub Stars into a searchable, categorized, personal repository library.

English · 中文

🧭 Overview

StarMagpie syncs your GitHub starred repositories to your Mac and keeps them useful after the initial star. It stores repository metadata locally, lets you search across names, descriptions, languages, topics, and notes, and gives each repository a category so your Stars become easier to revisit.

The app is intentionally small and native. It uses SwiftUI, SwiftData, URLSession, and macOS Keychain. There is no backend service, no account sync server, and no token storage outside Keychain.

✨ Highlights

• Native macOS experience built with SwiftUI.
• GitHub Personal Access Token sign-in with secure Keychain storage.
• Paginated GitHub Stars sync using application/vnd.github.star+json, preserving starred_at.
• Local persistence with SwiftData.
• Fast search across repository name, full name, description, topics, language, and notes, with ascending or descending sorting.
• Two-column repository browser with list and card view modes.
• Built-in keyword categories plus manual category overrides.
• Dedicated repository detail modal with README preview, notes, link copying, GitHub opening, and unstarring.
• JSON import and export for local repository data, categories, notes, and last viewed timestamps.
• English and Simplified Chinese localization with an in-app language picker.
• Manual appearance switching for Follow System, Light, and Dark modes.

📚 Contents

• Requirements
• Install
• Usage
• GitHub Token Permissions
• Privacy
• Development
• Release Builds
• Localization
• Project Structure
• Contributing
• License

🖥️ Requirements

• macOS 14.0 or later
• Xcode 26 or later
• XcodeGen

Install XcodeGen with Homebrew:

brew install xcodegen

📦 Install

⬇️ Download a release

Download StarMagpie-unsigned.dmg from the GitHub Releases page once releases are published. Open the DMG and drag StarMagpie.app to Applications.

The project does not use an Apple Developer certificate yet, so release packages are not signed with Developer ID and are not notarized by Apple. macOS Gatekeeper will warn that the app is from an unidentified developer.

🛠️ Build from source

git clone https://github.com/yangsonhung/starmagpie.git
cd starmagpie
xcodegen generate
open StarMagpie.xcodeproj

Select the StarMagpie scheme in Xcode and run the app.

🚀 Usage

1. Create a classic GitHub Personal Access Token with access to your starred repositories.
2. Launch StarMagpie and sign in with the token.
3. Click Sync to load your starred repositories.
4. Browse repositories in list or card mode, then click a repository to open its detail modal.
5. View metadata, README, category, notes, and quick actions in the detail modal.
6. Use search, language filtering, sort fields, sort direction, categories, and notes to organize repositories.
7. Use the toolbar pickers to switch app language and appearance.
8. Use the Data menu to export or import a StarMagpie JSON archive.

Import behavior is merge-based: repositories with the same GitHub repo id are updated, and local repositories missing from the archive are kept.

🔐 GitHub Token Permissions

StarMagpie stores your token only in macOS Keychain. It never writes the token to SwiftData, logs, or project files.

Recommended minimum permissions:

• Full sync and unstar support: use a classic personal access token with public_repo.
• Private starred repositories: use a classic personal access token with repo.

Create a classic token:

1. Open GitHub classic token settings.
2. Enter a token name and expiration.
3. Select one permission set:
   • Public starred repositories only: check public_repo.
   • Public and private starred repositories: check repo.
4. Do not enable unrelated scopes such as workflow, write:packages, admin:org, gist, notifications, user, delete_repo, project, or key-management scopes.
5. Generate the token, copy it once, and paste it into StarMagpie.
6. If you need to replace a token later, use StarMagpie's Update GitHub Token button. This only replaces the Keychain token and keeps local repositories, notes, and categories.

🛡️ Privacy

StarMagpie is local-first:

• No backend service.
• No remote analytics.
• No cross-device sync.
• GitHub tokens are stored in macOS Keychain only.
• Repository data, notes, categories, and import/export archives stay under your control.

🧑‍💻 Development

Generate the Xcode project:

xcodegen generate

Run tests:

xcodebuild test -scheme StarMagpie -destination 'platform=macOS'

Build the app:

xcodebuild build -scheme StarMagpie -destination 'platform=macOS'

Regenerate the app icon:

./scripts/generate-app-icon.swift

Build an unsigned release package:

./scripts/package-unsigned.sh

🏷️ Release Builds

Local unsigned packages are written to:

• dist/StarMagpie-unsigned.dmg
• dist/StarMagpie-unsigned.dmg.sha256
• dist/StarMagpie-unsigned.zip
• dist/StarMagpie-unsigned.zip.sha256

When a v* tag is pushed to GitHub, the Release Unsigned Build workflow builds the unsigned package and attaches it to the GitHub Release.

The build has no Apple TeamIdentifier. Xcode may still add an ad-hoc/linker signature to the executable, which is not a Developer ID signature.

🌐 Localization

The source code uses English strings as the base language. User-facing strings are localized through:

• StarMagpie/en.lproj/Localizable.strings
• StarMagpie/zh-Hans.lproj/Localizable.strings
• StarMagpie/en.lproj/InfoPlist.strings
• StarMagpie/zh-Hans.lproj/InfoPlist.strings

When adding UI text, update both English and Simplified Chinese localization files in the same change.

🗂️ Project Structure

StarMagpie/
├── StarMagpie/                 # App source
│   ├── App/                    # App entry and root views
│   ├── Models/                 # SwiftData models and filtering logic
│   ├── Services/               # GitHub API, Keychain, archive, and sync services
│   ├── Utilities/              # Localization, documents, and global settings helpers
│   ├── ViewModels/             # Detail loading and presentation state
│   ├── Views/                  # SwiftUI views
│   ├── Assets.xcassets/        # App icon and assets
│   ├── en.lproj/               # English localization
│   └── zh-Hans.lproj/          # Simplified Chinese localization
├── StarMagpieTests/            # Unit tests
├── .github/                    # Issue templates, PR template, CI, and release workflow
├── docs/                       # Documentation assets
├── scripts/                    # Local maintenance scripts
├── AGENTS.md                   # Agent development instructions
├── CLAUDE.md -> AGENTS.md      # Claude-compatible symlink
├── CONTRIBUTING.md             # Contribution guide
├── CODE_OF_CONDUCT.md          # Code of conduct
├── SECURITY.md                 # Security policy
├── SUPPORT.md                  # Support policy
├── LICENSE                     # GNU GPL v3
├── README.zh-CN.md             # Simplified Chinese README
└── project.yml                 # XcodeGen config

🤝 Contributing

Issues and pull requests are welcome. Please read:

• Contributing Guide
• Code of Conduct
• Security Policy

Use the GitHub issue templates when reporting bugs, asking questions, or proposing features. Include macOS version, Xcode version, reproduction steps, and relevant logs when applicable.

📄 License

StarMagpie is licensed under the GNU General Public License v3.0.