GitHub Follow Back

A TOS-compliant GitHub follower management tool that automatically follows back your followers with intelligent rate limiting. This tool respects GitHub's API limits and Terms of Service through conservative automation with built-in safeguards.

Features

• Track GitHub followers in a local database
• Automated follow-back with TOS-compliant rate limiting
• Conservative daily limits (default: 50 follows/day, well within GitHub's 5000 API calls/hour)
• Configurable delays between follow actions (default: 60 seconds)
• Smart request management that never violates GitHub's rate limits
• View follower statistics and history
• Manual mode available for selective following
• Docker support for easy deployment

How It Works

This tool automates following with strict TOS compliance:

1. Sync: Periodically fetches your current GitHub followers
2. Rate Limiting: Enforces daily follow limits and delays between actions
3. Auto-Follow: Automatically follows new followers within safe limits
4. Tracking: Keeps detailed records of all follow actions

TOS Compliance Strategy

GitHub allows 5,000 API requests per hour for authenticated users. This tool is extremely conservative:

• Default limit: 50 follows per day (0.06% of hourly limit)
• Delay between follows: 60 seconds minimum
• Typical usage: Most users get 1-5 new followers per day
• Maximum impact: Even at 50 follows/day with 60s delays, this uses only 50 API calls spread over time
• Safety margin: Uses <1% of available API quota, leaving 99%+ for other operations

The tool automatically tracks daily usage and resets counters at midnight, ensuring you never exceed configured limits.

Prerequisites

• Python 3.8 or higher
• A GitHub Personal Access Token with user:follow scope
• Docker (optional, for containerized deployment)

Installation

Local Installation

1. Clone the repository:

git clone https://github.com/onamfc/github-follow-back
cd github-follow-notifier

2. Install dependencies:

pip install -r requirements.txt

3. Install the package:

pip install -e .

Docker Installation

1. Build the Docker image:

docker-compose build

Configuration

1. Create a GitHub Personal Access Token:

   • Go to https://github.com/settings/tokens
   • Click "Generate new token (classic)"
   • Give it a name (e.g., "Follow Notifier")
   • Select the user:follow scope
   • Click "Generate token"
   • Copy the token (you won't see it again!)

2. Configure the tool:

github-follow-notifier setup

Enter your GitHub token when prompted.

Usage

Automated Mode (Recommended)

Enable automation:

github-follow-notifier auto enable --limit 50 --delay 60

Options:

• --limit: Maximum follows per day (default: 50)
• --delay: Seconds between follow actions (default: 60)

Start the automation loop:

github-follow-notifier run

This will continuously:

• Check for new followers every hour (configurable)
• Automatically follow them back within your daily limit
• Log all actions with timestamps
• Stop when daily limit is reached and resume the next day

Run once and exit:

github-follow-notifier run --once

Check automation status:

github-follow-notifier auto status

Disable automation:

github-follow-notifier auto disable

Manual Mode Commands

Sync followers from GitHub:

github-follow-notifier sync

View all followers:

github-follow-notifier list

View pending notifications:

github-follow-notifier list --pending

View followers not followed back:

github-follow-notifier list --not-followed

Follow a specific user back:

github-follow-notifier follow <username>

Follow all pending followers (with confirmation):

github-follow-notifier follow-all

View statistics:

github-follow-notifier status

Docker Usage

Run automation with Docker Compose:

# Enable automation
docker-compose run github-follow-notifier github-follow-notifier auto enable

# Start continuous automation
docker-compose run github-follow-notifier github-follow-notifier run

# Run once
docker-compose run github-follow-notifier github-follow-notifier run --once

Workflow Examples

Automated Workflow (Recommended)

1. Initial Setup:

github-follow-notifier setup
github-follow-notifier sync

2. Enable Automation:

github-follow-notifier auto enable --limit 50 --delay 60

3. Start Automation Loop:

github-follow-notifier run

Leave it running! It will automatically handle new followers as they come.

Manual Workflow

1. Initial Setup:

github-follow-notifier setup
github-follow-notifier sync

2. Daily Check for New Followers:

github-follow-notifier sync

3. Review and Follow Back:

github-follow-notifier list --not-followed
github-follow-notifier follow alice
github-follow-notifier follow bob

4. Check Your Stats:

github-follow-notifier status

Database

The tool uses a local SQLite database stored at ~/.github_follow_notifier/followers.db:

Database Location

• Local: ~/.github_follow_notifier/followers.db
• Docker: Persisted in Docker volume github-follow-data

Tables

followers

• Tracks all your GitHub followers
• Stores username, profile URL, follow timestamps
• Tracks notification and follow-back status

settings

• Stores your GitHub token (locally encrypted)
• Stores check interval preferences
• Tracks last sync time and automation settings

Rate Limiting & TOS Compliance

Built-in Safeguards

1. Daily Follow Limit: Default 50 follows/day (configurable), far below GitHub's capacity
2. Follow Delay: Minimum 60 seconds between follows (configurable)
3. Automatic Tracking: Database tracks daily usage and resets at midnight
4. Smart Scheduling: Only processes follows when new followers exist
5. API Monitoring: Built-in rate limit checking prevents overuse

Why This is TOS-Compliant

• Realistic usage: Most users receive 1-5 new followers per day
• Conservative limits: Even at maximum (50/day), uses <1% of GitHub's 5000 calls/hour
• Natural pacing: 60-second delays make activity appear human
• No spam: Only follows users who followed you first
• Transparent: All actions are logged and trackable
• Voluntary: Followers choose to follow you; you're just reciprocating

Comparison to GitHub's Limits

Metric	GitHub Limit	Tool Default	Usage %
API Calls/Hour	5,000	~2-5	0.1%
Follows/Day	No official limit	50	Conservative
Follow Delay	None specified	60 seconds	Human-like

Security

• Your GitHub token is stored locally in SQLite database
• Database file is stored in your home directory with restricted permissions
• The tool never shares your token or data with third parties
• All data stays on your machine (or Docker volume)
• Rate limiting prevents accidental API abuse

Monitoring

Check your current usage and limits:

github-follow-notifier status

This shows:

• Automation status (enabled/disabled)
• Daily follow limit and current usage
• Follows remaining today
• GitHub API rate limit status

Contributing

Contributions are welcome! Please ensure any changes maintain compliance with GitHub's Terms of Service.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Disclaimer

This tool is designed to help you manage your GitHub followers in a way that respects GitHub's Terms of Service through intelligent rate limiting and conservative automation. It only follows users who have already followed you, uses minimal API resources, and includes safeguards to prevent abuse. Use responsibly and in accordance with GitHub's policies.

Support

For issues, questions, or suggestions, please open an issue on GitHub.