Follow Sync is a modern GitHub network manager designed for power users. It helps you discover non-mutual connections, identify "ghost" accounts, and analyze your network efficiently.
- Comprehensive Network Analysis: Get a clear picture of who you follow that doesn't follow you back, and vice-versa.
- Ghost Account Detection: Identify "ghost" connections—accounts that have been deleted or suspended but still appear in your network lists. This provides a more accurate understanding of your active network, as these connections cannot be removed through the API.
- Single-Click Follow/Unfollow: Manage your network directly from the Follow Sync interface with optimistic UI updates for a seamless experience.
- Adaptive Caching: Utilizes your own GitHub Gists as a database, with an intelligent caching mechanism to respect GitHub's API rate limits while keeping your data fresh.
- Secure & Private: All your network data is stored in a private Gist that you own. Follow Sync never stores your data on its servers.
- Bulk Actions: Select multiple users and perform follow/unfollow operations on them sequentially with progress tracking.
- Customizable Settings: Tailor your experience with settings for pagination, avatar display, and more.
- Framework: Next.js 15+ (App Router)
- Language: TypeScript
- State Management: TanStack Query (React Query) for server state and Zustand for client state.
- Authentication: NextAuth.js with GitHub OAuth
- API: GitHub GraphQL API
- Styling: Tailwind CSS
- Hosting: Vercel
Follow Sync employs a client-heavy, GitHub-as-Infrastructure architecture. It leverages GitHub's own systems for authentication, data fetching, and even data persistence.
- Authentication: You authorize the Follow Sync GitHub OAuth App, granting it limited, user-scoped permissions.
- Data Fetching: The app calls the GitHub GraphQL API to fetch your follower and following lists.
- Analysis & Caching: The data is analyzed in the client to find non-mutuals. The results are then stored in a private GitHub Gist owned by you. This Gist acts as a cache for all subsequent loads.
- UI: The interface is built with React Server Components and loads instantly from the Gist cache, triggering background refreshes based on the age and size of your network data.
This project is currently in active development.
- Phase 1: Authentication & App Shell
- Phase 2: Core Data Pipeline (GraphQL)
- Phase 3: Adaptive Gist Caching
- Phase 4: Ghost-Detection Pipeline
- Phase 5: Follow/Unfollow Operations
- Phase 6: UI/UX Polish & Onboarding
- Phase 7: Performance Improvements & Testing
- Phase 8: User Settings
To run this project locally, you first need to create and configure a GitHub OAuth App.
- Go to Settings > Developer settings > OAuth Apps and click New OAuth App.
- Fill in the required application details:
- Application name:
Follow Sync (local) - Homepage URL:
http://localhost:3000 - Authorization callback URL:
http://localhost:3000/api/auth/callback/github
- Application name:
- Click Register application.
- On the next page, generate a client secret and copy it.
Create a file named .env.local in the project root. You will need the Client ID and the Client secret from your GitHub App settings page.
# .env.local
# Get these from your GitHub App page
AUTH_GITHUB_ID="YOUR_CLIENT_ID"
AUTH_GITHUB_SECRET="YOUR_CLIENT_SECRET"
# A random string for signing tokens.
# You can generate one with: openssl rand -hex 32
AUTH_SECRET="YOUR_AUTH_SECRET"
# Personal Access Token (for graphql code generation)
GITHUB_PAT="YOUR_GITHUB_PAT"
# Domain
NEXT_PUBLIC_DOMAIN="follow-sync.vercel.app"Once your .env.local file is configured, you can install the dependencies and start the development server.
yarn install
yarn devOpen http://localhost:3000 with your browser to see the result.
This project is licensed under the MIT License. See the LICENSE file for details. See the LICENSE file for details.