A bookmark‑style tool for collecting and managing GitHub projects, suitable for anyone who loves to curate GitHub repositories.
GitShelf is accompanied by a Dual-Browser Certified extension for Google Chrome and Microsoft Edge. It allows you to capture repositories and profiles directly from the GitHub interface with a single click.
- One-click Capture: Save any repository or user profile without leaving your current tab.
- Chrome & Edge Native: Optimized for the latest Chromium-based browsers.
- Secure Bridge: Background synchronization with your web session using AES-GCM encryption.
- Source Code: GitShelf Extensions
GitShelf is a browser-based bookmark manager for GitHub repositories. Sign in with your GitHub account, add any public repo you care about, tag and filter them, and keep your collection in sync — all stored privately in your own GitHub Gist as JSON. No server. No database. No tracking.
- Add any GitHub repository or profile by URL or shorthand (e.g.,
owner/repoorowner) - Profile Bookmarking — Add any GitHub user or organization to generate a visual Profile Dashboard showing:
- User bio, social links, and status emojis
- Followers/Following counts and location
- Rendered "Special README" repository
- Pinned and Popular repositories with star/fork metrics
- Folders & Workspaces — Organize your shelf into custom, color-coded folders
- Drag & Drop Organization — Easily move items into folders by dragging them from the list to the sidebar
- Smart Update Indicators — Blinking visual indicators (🔴) appear when a project has new commits since your last GitHub visit
- Star & Release Tracking — Monitor star growth trends (↑/↓) and stay updated with automatically detected latest releases
- Smart Favorites (♥) — Pin important projects for quick access; favorites are always pinned to the top of any view
- Three view modes — Card, Table, and Grouped views
- Tokenized Search — Full-text search across name, owner, description, and language, plus support for
@topicmentions to instantly filter by GitHub topics - Bulk actions — Tag, Move, or Delete multiple items at once from the toolbar
- Intelligent Trash Bin — Deleted items are moved to a secure Trash rather than being permanently removed, allowing for easy restoration.
- One-click Restore — Restore items to their original folders instantly
- Configurable Retention — Automatically clear items from Trash after 7, 14, 30, or 90 days (or keep them forever)
- Sync Isolation — Trash data is synchronized via Gist separately to ensure peak performance and data safety
- Create custom tags with adjustable color palettes, supporting multiple tags per repo, with multi-select filtering to find exactly what you need.
- Advanced Filter Bar — filter by Type (Repo/Profile), Favorites, Status, Tag, Language, Stars, and Recency
- Status tracking — Automatically detects
active,archived,renamed,stale, ornot_found - Language breakdown — Visual distribution bar for repository languages
- Installable PWA — Install GitShelf on your iOS or Android device for a native-like app experience.
- System Share Integration — GitShelf registers as a Share Target on your mobile device. You can share any GitHub URL directly from your mobile browser or the GitHub app to GitShelf.
- Smart Inbox Queue — Shared links are safely pushed to an independent
gitshelf_pending.jsonqueue in your Gist. - Desktop Pop Verification — Next time you open GitShelf on your desktop, it automatically fetches your mobile shares and displays them in a "Pending Inbox" banner for you to review and import into your database in one click.
- One-click sync to refresh metadata (stars, description, language, latest release) for all bookmarked repos
- Offline-First — All data is persisted to IndexedDB, allowing you to browse and manage your shelf without an internet connection. Changes sync to Gist once you're back online.
- GitHub API rate-limit badge displayed in Settings so you always know your quota
- Auto-backup your shelf to a private GitHub Gist on an interval you choose (5–30 min)
- Manual backup and restore from Gist with a single click
- Encrypted token storage keeps your GitHub access token safe in
localStorage
- Click any repo to open a drawer with the rendered README — full GitHub-Flavored Markdown, images, and syntax highlighting
- Relative image and link paths are resolved to GitHub raw content automatically
- Export your entire shelf as a JSON file for offline backup
- Import from a JSON backup or from a browser bookmarks export
- Interface — Responsive user interface
- Themes — Light and Dark theme support
| Layer | Technology |
|---|---|
| Framework | React 19 + TypeScript 5 |
| Build Tool | Vite 7 |
| State | Zustand |
| Styling | Tailwind CSS v4 |
| Validation | Zod |
| Auth | GitHub OAuth 2.0 (gist + read:user scopes only) |
| Storage | GitHub Gist (cloud) + IndexedDB / localStorage (local) |
| Markdown | react-markdown + remark-gfm + rehype-sanitize |
| Icons | Lucide React |
- Node.js 20+
- A GitHub OAuth App (for local development)
git clone https://github.com/TSHsoft/GitShelf.git
cd GitShelfnpm installnpm run devFollow the local URL shown in your terminal (usually http://localhost:5173).
Note: To enable GitHub OAuth sign-in locally, you'll need to register a GitHub OAuth App, deploy a Cloudflare Worker, and configure your local
.envfile as described in the GitHub OAuth Setup section.
npm run buildGitShelf requests only minimal, read-only permissions:
| Scope | Reason |
|---|---|
gist |
Read and write your private backup Gist |
read:user |
Display your username and avatar |
No write access to your repositories is ever requested.
To self-host with your own OAuth App, you need a GitHub OAuth App and a Cloudflare Worker (to safely exchange the OAuth code for an access token without exposing your Client Secret to the browser).
- Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
- Set the Homepage URL to your deployed URL or
http://localhost:5173for local development. - Set the Authorization callback URL to your deployment URL or
http://localhost:5173. - Generate a Client ID and a Client Secret.
Create a new Cloudflare Worker that accepts a POST request with { code }, exchanges it via https://github.com/login/oauth/access_token, and returns the { access_token }.
- In your Cloudflare Worker settings, configure the environment variables:
GITHUB_CLIENT_IDGITHUB_CLIENT_SECRET
- Ensure the worker handles CORS properly for your domain.
Create a .env file based on .env.example:
VITE_GITHUB_CLIENT_ID=your_github_client_id
VITE_WORKER_URL=https://your-worker-name.your-worker-subdomain.workers.dev
VITE_CRYPTO_SECRET=your_generated_random_secret_hereImportant: You must generate a secure, random string for
VITE_CRYPTO_SECRET. This key is used to encrypt your GitHub access token in the browser's local storage. GitShelf uses account-bound encryption: This secret is combined with your unique GitHub User ID to derive the final encryption key, ensuring that tokens are securely tied to your specific account. You can easily generate a strong random 32-byte hex string by running this command in your terminal:node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"For online deployments of the frontend app, make sure to add
VITE_CRYPTO_SECRETto your hosting provider's environment variables (e.g., your Vercel project settings or Cloudflare Pages settings). It is NOT needed in your Cloudflare Worker.
You can deploy the GitShelf frontend to any static hosting provider. Here is how to do it with Vercel:
- Import your Project: Link your GitHub repository to Vercel.
- Configure Environment Variables: In your Vercel Project Settings, go to Environment Variables and add the following:
VITE_GITHUB_CLIENT_IDVITE_WORKER_URLVITE_CRYPTO_SECRET(Use the 32-byte hex string generated earlier)
- Deploy: Vercel will automatically build and deploy your app.
- Note: If you update your environment variables later, you must Redeploy the latest deployment in the Vercel dashboard for the changes to take effect.
Found a bug or have a suggestion? Please open an issue. We appreciate your help in making GitShelf better!
Distributed under the MIT License. See LICENSE for details.
Made with ❤️ — Star ⭐ this repo if you find it useful!