gh-social 1.0.3

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. Currently includes Follow Back and Unfollow tools, with more coming soon.

Tools

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

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

╭──────────────────────────────────────────────╮
│  🔍  gh-social  v1.0.3                      │
╰──────────────────────────────────────────────╯

  Choose a tool:

  1.  Follow Back   — Follow all followers of a target user
  2.  Unfollow      — Unfollow users who don't follow you back

  0.  Exit

  → Choice (0-2):

CLI Mode

# Follow Back
gh-social follow ajangsupardi              # Dry-run
gh-social follow ajangsupardi --execute    # Execute
gh-social follow ajangsupardi --limit 100  # 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

Project Structure

gh-social/
├── gh_social/              # Package
│   ├── __init__.py           # Version
│   ├── __main__.py           # Entry point
│   ├── cli.py                # CLI dispatcher + interactive menu
│   ├── api.py                # GitHub API (auth, pagination)
│   ├── models.py             # Data models & bot detection
│   ├── formatting.py         # Output formatting
│   └── tools/
│       └── social.py         # Follow back & unfollow logic
├── pyproject.toml            # Pip installable config
├── README.md
└── LICENSE

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

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.