gh-social

CLI tools for GitHub — follow back, unfollow, and more.

A fast, modular toolkit for common GitHub operations. Includes Follow Back, Unfollow, and Follow Stargazers tools.

Tools

Features

• Interactive Menu — Run without arguments for a guided menu experience
• Concurrent Execution — Uses ThreadPoolExecutor with 16 workers for fast API operations
• Smart Bot Detection — Identifies spam/bot accounts using a 2-of-3 heuristic
• Dry-Run Mode — Preview targets before executing any actions
• Rate Limit Aware — Checks GitHub API rate limits before proceeding
• JSON Output — Machine-readable output for scripting and automation

Requirements

• Python 3.10+
• GitHub CLI (gh) — must be installed and authenticated
• rich >= 13.0 — modern terminal output

Authentication

The toolkit uses your gh CLI credentials:

gh auth login
gh auth refresh -h github.com -s user

Installation

Note: On Debian/Ubuntu 23.04+ the system Python is externally managed (PEP 668). Use a virtual environment or pipx to avoid installation errors.

With pipx (Recommended)

pipx install gh-social

From PyPI

pip install gh-social

From Source (Development)

git clone https://github.com/ajangsupardi/gh-social.git
cd gh-social
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Usage

Interactive Mode

Run without arguments to see the menu:

gh-social

CLI Mode

# Follow Back
gh-social follow ajangsupardi              # Dry-run
gh-social follow ajangsupardi --execute    # Execute
gh-social follow ajangsupardi --limit 100  # Limit

# Follow Stargazers
gh-social stargazers ajangsupardi/gh-social              # Dry-run
gh-social stargazers ajangsupardi/gh-social --execute    # Execute
gh-social stargazers ajangsupardi/gh-social --limit 50   # Limit

# Unfollow
gh-social unfollow                         # Dry-run
gh-social unfollow --execute               # Execute
gh-social unfollow --limit 100             # Limit

# Common flags
gh-social follow ajangsupardi --json       # JSON output
gh-social follow ajangsupardi --execute --include-bots

As Library

from gh_social.api import get_session, api_paginate, follow_user
from gh_social.models import enrich_users_concurrent

# Initialize session
get_session()

# Use API functions directly
followers = api_paginate("users/octocat/followers")
follow_user("octocat")

Flags

How It Works

Follow Back

1. Authenticate via gh CLI token
2. Fetch target user's followers (paginated, concurrent)
3. Fetch your following list to identify already-followed users
4. Filter out: yourself, already-followed, and optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute follows concurrently

Unfollow

1. Authenticate via gh CLI token
2. Fetch your followers & following lists (concurrent)
3. Find: users you follow who DON'T follow you back
4. Filter out: optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute unfollows concurrently

Follow Stargazers

1. Authenticate via gh CLI token
2. Fetch stargazers of target repo (paginated, concurrent)
3. Fetch your following list to identify already-followed users
4. Filter out: yourself, already-followed, and optionally bots
5. Enrich user details concurrently (name, bio, repos)
6. Display table preview (dry-run) or execute follows concurrently

Bot Detection

Accounts are flagged as potential bots when 2 out of 3 conditions are met:

License

MIT License — see LICENSE for details.