gh-social 1.2.2

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

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

Tool	Description
follow	Follow all followers of any GitHub user
unfollow	Unfollow users who don't follow you back
stargazers	Follow users who starred a repository

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

Flag	Description	Default
--execute	Execute action (otherwise dry-run)	false
--limit N	Limit number of users processed	0 (all)
--include-bots	Include bot accounts	false
--json	Output in JSON format	false

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:

Condition	Description
Default avatar	Uses GitHub's default identicon
Empty bio	No bio or whitespace only
Zero repos	No public repositories

License

MIT License — see LICENSE for details.