Pull Shark Automation

Automate GitHub PR creation at scale with intelligent token rotation, proxy support, and real-time notifications. Create thousands of PRs effortlessly using sequential or high-speed parallel modes (62 PRs/min). Features: multi-token management, auto-merge, state persistence, Discord/Slack webhooks, async operations, and Windows compatibility.

From itxashancode·Updated June 13, 2026·View on GitHub·

This tool is designed for **educational purposes** to understand GitHub automation, CI/CD workflows, and API integration. Use responsibly and in accordance with GitHub's Terms of Service. The project is written primarily in Python, distributed under the MIT License license, first published in 2026. Key topics include: async, automation, batch-processing, ci-cd, devops.

🦈 GitHub Pull Shark Automation

⚠️ Educational Purpose Only

This tool is designed for educational purposes to understand GitHub automation, CI/CD workflows, and API integration. Use responsibly and in accordance with GitHub's Terms of Service.

🏆 Earn Your Pull Shark Badge

<div align="center"> <img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark.png" width="180" alt="Pull Shark Badge"/> <table> <tr> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark.png" width="80"/><br/><b>Default</b><br/>2 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Bronze.png" width="80"/><br/><b>Bronze</b><br/>16 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Silver.png" width="80"/><br/><b>Silver</b><br/>128 PRs</td> <td align="center"><img src="https://github.com/drknzz/GitHub-Achievements/blob/main/Media/Badges/Pull-Shark/PNG/PullShark_Gold.png" width="80"/><br/><b>Gold</b><br/>1024 PRs</td> </tr> </table> </div> <p align="center"> <i>Automate PR creation and merging to unlock all achievement tiers!</i> </p> </div>

🎯 What Is Pull Shark Automation?

A powerful Python automation framework that streamlines GitHub Pull Request workflows at scale. Perfect for developers who want to:

🎯 Use Case	📊 Benefit
Batch Documentation Updates	Update README files across multiple branches
Configuration Management	Apply settings changes repository-wide
CI/CD Testing	Stress-test your automation pipelines
Achievement Hunting	Earn GitHub badges efficiently
Learning & Research	Study automation patterns and workflows

</div>

📑 Table of Contents

🌟 Features	🏗️ Architecture	📦 Installation	⚙️ Configuration
🚀 Usage	🔧 Components	⚡ Performance	🔐 Security
🐛 Troubleshooting	📈 Optimization	🤝 Contributing	📄 License

</div>

🌟 Features

🎯 Core Capabilities

yaml
✅ Automated PR Creation
   └─ Generate 100-10,000+ PRs
   
✅ Smart Auto-Merge
   └─ Intelligent PR merging
   
✅ Dual Execution Modes
   └─ Sequential & Parallel
   
✅ State Management
   └─ Resume from interruptions
   
✅ Dry Run Mode
   └─ Test without commits

</td> <td width="50%" valign="top">

🔧 Advanced Features

yaml
✅ Multi-Token Rotation
   └─ Automatic token switching
   
✅ Proxy Management
   └─ Built-in scraping & rotation
   
✅ Real-Time Notifications
   └─ Discord & Slack webhooks
   
✅ Rate Limit Handling
   └─ Smart API throttling
   
✅ Exponential Backoff
   └─ Intelligent retry logic

</td> </tr> </table> </div>

🎬 How It Works

mermaid
%%{init: {'theme':'dark','themeVariables': {'primaryColor':'#ff6b6b','primaryTextColor':'#fff','primaryBorderColor':'#ff6b6b','lineColor':'#4ecdc4','secondaryColor':'#ffe66d','tertiaryColor':'#a8dadc'}}}%%
graph TB
    Start([🚀 Start Automation]) --> Config[📋 Load Configuration]
    Config --> Mode{🔀 Choose Mode}
    
    Mode -->|Sequential| Seq[📝 main.py<br/>Single Thread]
    Mode -->|Parallel| Par[⚡ parallel_automation.py<br/>Multi-Thread]
    
    Seq --> Git[🔧 Git Operations]
    Par --> Git
    
    Git --> Branch[🌿 Create Branch]
    Branch --> Commit[💾 Commit Changes]
    Commit --> Push[📤 Push to Remote]
    Push --> PR[🎯 Create PR]
    
    PR --> AutoMerge{🤖 Auto-merge?}
    AutoMerge -->|Yes| Merge[✅ Merge PR]
    AutoMerge -->|No| Next{📊 More PRs?}
    Merge --> Next
    
    Next -->|Yes| Git
    Next -->|No| Notify[📢 Send Notifications]
    Notify --> End([🎉 Complete!])
    
    style Start fill:#2ecc71,stroke:#27ae60,stroke-width:3px,color:#fff
    style End fill:#e74c3c,stroke:#c0392b,stroke-width:3px,color:#fff
    style PR fill:#3498db,stroke:#2980b9,stroke-width:2px,color:#fff
    style Merge fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:#fff

</div>

🏗️ Architecture

System Design Overview

┌─────────────────────────────────────────────────────────────────┐
│                    🦈 Pull Shark Automation                      │
│                     Core Orchestration Layer                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                ┌───────────────┴───────────────┐
                │                               │
        ┌───────▼────────┐            ┌────────▼───────┐
        │  📝 Sequential │            │  ⚡ Parallel   │
        │    main.py     │            │ parallel_*.py  │
        │   Reliable     │            │   Fast & Async │
        └───────┬────────┘            └────────┬───────┘
                │                              │
                └──────────────┬───────────────┘
                               │
        ┌──────────────────────┼──────────────────────┐
        │                      │                      │
   ┌────▼─────┐         ┌─────▼────┐         ┌──────▼─────┐
   │ 🔧 Git   │         │ 🐙 GitHub│         │ 🔑 Token   │
   │ Manager  │         │   Tool   │         │  Manager   │
   │ Ops      │         │ API Wrap │         │  Rotation  │
   └────┬─────┘         └─────┬────┘         └──────┬─────┘
        │                     │                      │
        └─────────────────────┼──────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   ┌────▼─────┐         ┌────▼─────┐         ┌────▼─────┐
   │ 🌐 Proxy │         │ 📢 Notify│         │ 📝 Logger│
   │ Rotation │         │ Webhooks │         │  System  │
   └──────────┘         └──────────┘         └──────────┘

</div>

🔑 Component Matrix

Component	Role	Performance	Features
main.py	📝 Sequential	⭐⭐⭐⭐⭐ Stable	Single-thread, persistent
parallel_automation.py	⚡ Parallel	⭐⭐⭐⭐⭐ Fast	Multi-thread, async
git_manager.py	🔧 Git Ops	⭐⭐⭐⭐	Branch, commit, push
github_tool.py	🐙 API	⭐⭐⭐⭐	PR create/merge, limits
token_manager.py	🔑 Tokens	⭐⭐⭐⭐⭐	Multi-token rotation
proxy_manager.py	🌐 Proxies	⭐⭐⭐	Scraping & rotation
notifier.py	📢 Alerts	⭐⭐⭐⭐	Discord & Slack
logger.py	📝 Logs	⭐⭐⭐⭐⭐	File & console

</div>

📦 Installation

🚀 Quick Start Guide

Prerequisites Checklist

bash
✅ Python 3.8 or higher
✅ Git 2.0 or higher
✅ GitHub CLI (gh)
✅ Active GitHub account
✅ Write access to target repository

Step 1️⃣: Clone Repository

<details open> <summary><b>📥 Download the Code</b></summary>

bash
# Clone via HTTPS
git clone https://github.com/itxashancode/Pull-Shark-Automation.git

# Or clone via SSH
git clone git@github.com:itxashancode/Pull-Shark-Automation.git

# Navigate to directory
cd Pull-Shark-Automation

</details>

Step 2️⃣: Install Dependencies

<details open> <summary><b>🐍 Python Packages</b></summary>

bash
# Install all required packages
pip install -r requirements.txt

# Or use pip3 on some systems
pip3 install -r requirements.txt

📦 What Gets Installed:

Package	Purpose	Version
`requests`	HTTP/API calls	≥2.28.0
`aiohttp`	Async HTTP client	≥3.8.5
`aiofiles`	Async file operations	≥23.1.0
`gitpython`	Git automation	≥3.1.31
`beautifulsoup4`	HTML parsing	≥4.12.0
`colorama`	Terminal colors	≥0.4.6
`schedule`	Task scheduling	≥1.2.0

</details>

Step 3️⃣: Install GitHub CLI

<details> <summary><b>🍎 macOS Installation</b></summary>

bash
# Using Homebrew
brew install gh

# Verify installation
gh --version

</details> <details> <summary><b>🐧 Linux Installation</b></summary>

bash
# Debian/Ubuntu
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | \
  sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | \
  sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

sudo apt update
sudo apt install gh -y

# Fedora/RHEL/CentOS
sudo dnf install gh -y

# Arch Linux
sudo pacman -S github-cli

# Verify installation
gh --version

</details> <details> <summary><b>🪟 Windows Installation</b></summary>

powershell
# Using winget
winget install --id GitHub.cli

# Or using Chocolatey
choco install gh

# Or using Scoop
scoop install gh

# Verify installation
gh --version

</details>

Step 4️⃣: Authenticate GitHub

<details open> <summary><b>🔐 Login to GitHub</b></summary>

bash
# Start authentication
gh auth login

# Follow the interactive prompts:
# 1. Choose: GitHub.com
# 2. Protocol: HTTPS
# 3. Authenticate Git: Yes
# 4. Method: Login with a web browser

# Verify authentication
gh auth status

Expected Output:

✓ Logged in to github.com as YourUsername
✓ Git operations for github.com configured to use https protocol.
✓ Token: *******************

</details>

✅ Installation Complete!

Ready to configure? Proceed to ⚙️ Configuration

</div>

⚙️ Configuration

🎛️ Setup Your Automation

📋 File 1: Main Config (`config.json`)

json
{
  "repo_path": ".",
  "base_branch": "main",
  "readme_file": "README.md",
  "pr_count": 2000,
  "delay_seconds": 30,
  "auto_merge": true,
  "dry_run": false,
  "max_retries": 3,
  "use_free_proxies": true,
  "max_concurrent": 10,
  "discord_webhook": "https://discord.com/api/webhooks/YOUR_WEBHOOK_HERE",
  "slack_webhook": "https://hooks.slack.com/services/YOUR_WEBHOOK_HERE"
}

<details> <summary><b>📖 Configuration Reference</b></summary>

Parameter	Type	Default	Description
`repo_path`	string	`"."`	Path to your Git repository
`base_branch`	string	`"main"`	Target branch for PRs
`readme_file`	string	`"README.md"`	File to modify in each commit
`pr_count`	integer	`2000`	Total PRs to create
`delay_seconds`	integer	`30`	Wait time between PRs (sequential)
`auto_merge`	boolean	`true`	Automatically merge created PRs
`dry_run`	boolean	`false`	Test mode (no actual changes)
`max_retries`	integer	`3`	Retry attempts on failure
`use_free_proxies`	boolean	`true`	Enable proxy rotation
`max_concurrent`	integer	`10`	Parallel workers (parallel mode)
`discord_webhook`	string	`""`	Discord notification URL
`slack_webhook`	string	`""`	Slack notification URL

</details>

🔑 File 2: GitHub Tokens (`github_tokens.json`)

json
{
  "tokens": [
    {
      "name": "Primary Token",
      "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    {
      "name": "Secondary Token",
      "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    },
    {
      "name": "Backup Token",
      "token": "github_pat_11XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
  ]
}

<details> <summary><b>🔐 How to Generate GitHub Tokens</b></summary>

Step-by-Step Guide:

Navigate to GitHub Settings
- Click your profile → Settings
- Developer settings → Personal access tokens → Tokens (classic)
Generate New Token
- Click "Generate new token (classic)"
- Name: Pull Shark Automation
- Expiration: 90 days (recommended)
Select Required Scopes ✅
- ☑️ repo - Full control of private repositories
- ☑️ workflow - Update GitHub Action workflows
- ☑️ write:packages - Upload packages
Generate & Copy Token
- Click "Generate token"
- ⚠️ Copy immediately (shown only once!)
- Add to github_tokens.json

📊 Rate Limits:

Single token: 5,000 requests/hour
Multiple tokens: Rotates automatically for 15,000+/hour

🔒 Security Tips:

Never commit tokens to Git
Rotate every 30-90 days
Use fine-grained tokens when possible
Enable 2FA on your account

</details>

🌐 File 3: Proxies (`proxies.txt`)

text
# Free HTTPS proxies (ip:port format)
8.219.97.248:9090
47.91.34.69:3128
161.35.70.249:8080
165.227.196.37:3128
64.225.4.5:9999

# Authenticated proxies (protocol://user:pass@ip:port)
http://username:password@proxy.example.com:8080
socks5://admin:secret@10.0.0.1:1080

<details> <summary><b>🔍 Finding & Testing Proxies</b></summary>

🌐 Free Proxy Sources:

free-proxy-list.net - Updated hourly
proxyscrape.com - API available
spys.one - Global proxies

🧪 Test Proxies:

bash
# Test single proxy
curl -x http://8.219.97.248:9090 https://api.github.com/

# Test with timeout
curl -x http://proxy:port --max-time 5 https://api.github.com/

⚠️ Proxy Reliability:

Type	Reliability	Speed	Cost
Free	⭐⭐ Low	Slow	$0
Paid	⭐⭐⭐⭐⭐ High	Fast	$10-50/mo
Premium	⭐⭐⭐⭐⭐ Very High	Very Fast	$50-200/mo

💰 Recommended Paid Services:

Bright Data - Enterprise grade
Smartproxy - Good balance
Oxylabs - Large pool
Proxy-Cheap - Budget friendly

</details>

🔔 Optional: Webhook Setup

<details> <summary><b>💬 Discord Webhook</b></summary>

Setup Steps:

Open Discord server
Server Settings → Integrations → Webhooks
Click "New Webhook"
Set name: GitHub Bot or similar
Choose target channel
Click "Copy Webhook URL"
Paste into config.json

Webhook Format:

https://discord.com/api/webhooks/1234567890/ABCDEFGHIJKLMNOPQRSTUVWXYZ

Test Webhook:

bash
curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"content": "Test message from Pull Shark!"}'

</details> <details> <summary><b>💼 Slack Webhook</b></summary>

Setup Steps:

Go to api.slack.com/apps
Create New App → From scratch
App Name: GitHub Automation
Select workspace
Incoming Webhooks → Activate
Add New Webhook to Workspace
Select channel
Copy webhook URL
Paste into config.json

Webhook Format:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXX

Test Webhook:

bash
curl -X POST "YOUR_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"text": "Test from Pull Shark!"}'

</details>

✅ Configuration Complete!

Next: 🚀 Usage Guide

</div>

🚀 Usage

🎮 Command Center

🏁 Quick Start Commands

bash
# 1️⃣ Basic sequential run
python main.py

# 2️⃣ Fast parallel mode (recommended)
python parallel_automation.py --count 100 --concurrent 10

# 3️⃣ Test without creating PRs
python main.py --dry-run

# 4️⃣ Custom PR count
python main.py --count 500

# 5️⃣ Resume after interruption
python main.py  # Auto-resumes from state.json

📘 Sequential Mode (`main.py`)

bash
python main.py [OPTIONS]

⭐ Best For: Reliability, debugging, small batches (<500 PRs)

</div>

Option	Description	Example
`--count N`	Override PR count	`python main.py --count 200`
`--delay N`	Seconds between PRs	`python main.py --delay 60`
`--dry-run`	Test mode (no commits)	`python main.py --dry-run`
`--no-merge`	Disable auto-merge	`python main.py --no-merge`
`--reset`	Start from PR #1	`python main.py --reset`
`--use-proxies`	Enable proxy rotation	`python main.py --use-proxies`

📊 Example Output:

🚀 Starting from PR #1
⏱️  Delay: 30 seconds

🔹 Processing PR #1
  ├─ 🌿 Created branch: automation-1-a1b2c3d4
  ├─ 💾 Committed changes
  ├─ 📤 Pushed to remote
  └─ ✅ PR #12345 created successfully

✅ PR #12345 merged successfully
⏱️  Waiting 30 seconds...

🔹 Processing PR #2
...

⚡ Parallel Mode (`parallel_automation.py`)

bash
python parallel_automation.py [OPTIONS]

⭐ Best For: Speed, large batches (500-10,000 PRs)

</div>

Option	Description	Example
`--count N`	Number of PRs	`--count 1000`
`--concurrent N`	Parallel workers	`--concurrent 20`
`--start N`	Starting PR number	`--start 100`
`--no-proxy`	Disable proxies	`--no-proxy`
`--dry-run`	Test mode	`--dry-run`

📊 Example Output:

🚀 Initializing parallel automation...
📋 Loaded 3 GitHub tokens
🔍 Fetching proxies...
  📦 Total unique proxies collected: 342
  ✅ Working proxies: 87

🚀 Starting parallel automation

📈 Progress: 134/200 PRs
   ✓ Success: 130
   ✗ Failed: 4
   ⚡ Speed: 45.2 PRs/min

🎉 Automation Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 200 PRs
✅ Success: 196 (98%)
❌ Failed: 4 (2%)
⚡ Speed: 43.8 PRs/min
⏱️ Time: 4 minutes 34 seconds
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 Usage Examples

<details> <summary><b>Example 1: First-Time Setup (Bronze Badge)</b></summary>

Goal: Earn Bronze Pull Shark Badge (16 PRs)

bash
# Test with dry run first
python main.py --count 20 --dry-run

# Run actual automation
python main.py --count 20 --delay 15

# Expected time: ~5 minutes

Output:

🚀 Starting from PR #1
⏱️  Delay: 15 seconds

✅ PR #1-20 created successfully
🎉 Bronze Pull Shark Badge unlocked!

</details> <details> <summary><b>Example 2: Silver Badge (Parallel Mode)</b></summary>

Goal: Earn Silver Pull Shark Badge (128 PRs)

bash
# High-speed parallel mode
python parallel_automation.py --count 150 --concurrent 15

# Expected time: ~3-5 minutes

Output:

🚀 Starting parallel automation

📈 150/150 ✓ 147 ✗ 3 ⚡ 42.5 PRs/min

🎉 Silver Pull Shark Badge unlocked!
⏱️ Completed in 3 minutes 32 seconds

</details> <details> <summary><b>Example 3: Gold Badge (Maximum Speed)</b></summary>

Goal: Earn Gold Pull Shark Badge (1024 PRs)

bash
# Ultra-fast mode with 20 workers
python parallel_automation.py \
  --count 1024 \
  --concurrent 20

# Expected time: ~16-20 minutes with 3 tokens

Output:

🚀 Initializing parallel automation...
📋 Loaded 3 tokens
🌐 Working proxies: 87

📈 1024/1024 ✓ 982 ✗ 42 ⚡ 62.5 PRs/min

🎉🎉🎉 GOLD PULL SHARK UNLOCKED! 🎉🎉🎉
⏱️ Completed in 16 minutes 23 seconds

</details> <details> <summary><b>Example 4: Resume After Interruption</b></summary>

Scenario: Process interrupted at PR #350

bash
# Check current state
cat state.json
# Output: {"last_completed_pr": 350}

# Resume from PR #351
python main.py --count 500
# Automatically continues from #351

Output:

🔄 Resuming from PR #351 (found state.json)
⏱️  Remaining: 150 PRs

🔹 Processing PR #351
...

</details> <details> <summary><b>Example 5: Dry Run Testing</b></summary>

Goal: Test configuration without creating PRs

bash
python main.py --count 5 --dry-run

Output:

🔍 DRY RUN MODE - No actual commits

🔹 PR #1 Simulation
  📝 Would create branch: automation-1-abc123
  📝 Would modify: README.md
  📝 Would commit: "Automated update #1"
  📝 Would push to: origin/automation-1-abc123
  📝 Would create PR with title: "Automated PR #1"
  ✅ Simulation successful

🔹 PR #2 Simulation
...

✅ All 5 PRs simulated successfully

</details>

💡 Pro Tips

<table> <tr> <td>🎯 <b>Tip 1</b></td> <td>Start with <code>--dry-run</code> to test your configuration</td> </tr> <tr> <td>⚡ <b>Tip 2</b></td> <td>Use parallel mode with multiple tokens for maximum speed</td> </tr> <tr> <td>🔄 <b>Tip 3</b></td> <td>State files allow resuming - don't worry about interruptions</td> </tr> <tr> <td>📊 <b>Tip 4</b></td> <td>Monitor rate limits: <code>gh api rate_limit</code></td> </tr> <tr> <td>🌐 <b>Tip 5</b></td> <td>Enable proxies for extra speed and reliability</td> </tr> </table> </div>

🔧 Components Deep Dive

🏗️ System Architecture Breakdown

1️⃣ GitManager (`git_manager.py`)

🎯 Purpose: Handle all Git operations with retry logic and internet connectivity checks

🔑 Key Methods:

python
class GitManager:
    def __init__(self, base_branch: str, max_retries: int, logger)
    
    def wait_for_internet(self, timeout: int = 10) -> bool:
        """Wait for stable internet connection"""
        
    def run(self, command: List[str]) -> subprocess.CompletedProcess:
        """Execute git command with exponential backoff retry"""
        
    def sync_base(self) -> bool:
        """Sync base branch with remote"""
        
    def create_branch(self, name: str) -> bool:
        """Create and checkout new branch"""
        
    def commit(self, file: str, message: str) -> bool:
        """Stage and commit changes"""
        
    def push(self, branch: str) -> bool:
        """Push branch to remote"""

✨ Features:

<table> <tr> <td>⏱️ <b>Exponential Backoff</b></td> <td>Retry delays: 5s → 10s → 20s</td> </tr> <tr> <td>🌐 <b>Internet Check</b></td> <td>Validates connection before operations</td> </tr> <tr> <td>🔁 <b>Auto-Retry</b></td> <td>Configurable attempts (default: 3)</td> </tr> <tr> <td>⏲️ <b>Timeout Protection</b></td> <td>30-second command timeout</td> </tr> </table>

2️⃣ GitHubTool (`github_tool.py`)

🎯 Purpose: Wrap GitHub CLI with rate limit management and PR operations

🔑 Key Methods:

python
class GitHubTool:
    def check_rate_limit(self) -> Dict:
        """Query GitHub API rate limit status"""
        
    def create_pr(self, title: str, body: str, head: str) -> Optional[str]:
        """Create pull request via GitHub CLI"""
        
    def merge_pr(self, branch: str) -> bool:
        """Auto-merge pull request"""

📊 Rate Limit Flow:

mermaid
%%{init: {'theme':'dark'}}%%
graph LR
    A[Check Rate Limit] --> B{Remaining > 100?}
    B -->|Yes| C[Proceed]
    B -->|No| D[Calculate Wait Time]
    D --> E[Sleep Until Reset]
    E --> A
    
    style A fill:#3498db
    style C fill:#2ecc71
    style D fill:#f39c12

3️⃣ TokenManager (`token_manager.py`)

🎯 Purpose: Manage multiple GitHub tokens with automatic rotation

🔄 Rotation Algorithm:

python
def get_best_token():
    """
    1. Filter active tokens ✅
    2. Sort by remaining requests (descending) ⬇️
    3. Return token with highest limit ⭐
    4. Update last_used timestamp 🕐
    5. Decrement remaining count ➖
    """

📊 Token Statistics Example:

📋 Token Status Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Token 1 (Primary):    4,850 / 5,000 ⚡
Token 2 (Secondary):  5,000 / 5,000 ✅
Token 3 (Backup):     4,920 / 5,000 ⚡
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Available: 14,770 requests
Next Reset: 42 minutes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

4️⃣ ProxyManager (`proxy_manager.py`)

🎯 Purpose: Rotate proxies to distribute requests

🔄 Rotation Strategy:

python
# Round-robin with queue
proxy1 → proxy2 → proxy3 → proxy1 → ...

# Get proxy (auto-rotates)
proxy = proxy_queue.get()    # Returns proxy1
proxy_queue.put(proxy)       # Re-add to end

# Next: proxy2, then proxy3, then proxy1...

📊 Supported Formats:

python
# Simple proxies
"8.219.97.248:9090"
"http://47.91.34.69:3128"

# Authenticated proxies
"http://user:pass@proxy.example.com:8080"
"socks5://admin:secret@10.0.0.1:1080"

5️⃣ Notifier (`notifier.py`)

🎯 Purpose: Send real-time notifications

🎨 Notification Types:

Level	Color	Discord	Use Case
`info`	🔵 Blue	5814783	Progress updates
`success`	🟢 Green	3066993	PR created/merged
`warning`	🟡 Yellow	16776960	Non-critical errors
`error`	🔴 Red	15548997	Critical failures

📨 Example Notifications:

python
# Success
notifier.send(
    "✅ PR #123 created successfully\n"
    "Branch: automation-123-abc\n"
    "PR Number: #456",
    "success"
)

# Progress
notifier.send(
    "📊 Progress: 50/100 PRs\n"
    "Speed: 12.5 PRs/min",
    "info"
)

# Error
notifier.send(
    "❌ PR #75 failed\n"
    "Error: Network timeout",
    "error"
)

6️⃣ Logger (`logger.py`)

🎯 Purpose: Dual-output logging system

📝 Log Levels:

python
logger.info("✅ PR #123 created")       # General info
logger.warning("⚠️ Rate limit low")     # Warnings
logger.error("❌ Failed to push")       # Errors
logger.debug("🔍 Token: abc...")        # Debug info

📄 Sample Log Output:

2026-02-15 10:22:11 - INFO - Starting automation from PR #1
2026-02-15 10:22:15 - INFO - Created branch automation-1-abc123
2026-02-15 10:22:18 - INFO - Committed changes to README.md
2026-02-15 10:22:22 - INFO - Pushed branch automation-1-abc123
2026-02-15 10:22:25 - INFO - Created PR #12345
2026-02-15 10:22:28 - INFO - Merged PR #12345
2026-02-15 10:22:28 - WARNING - Rate limit: 4850 remaining

⚡ High-Performance Modules

🚀 Turbocharged Async Implementation

</div>

The high_performance package provides async-first implementations for maximum throughput and parallel processing. Fully Windows-compatible with proper event loop policies.

📁 Module Structure

high_performance/
├── __init__.py              # 📦 Package exports
├── git_manager.py          # 🔧 Async Git operations
├── github_tool.py          # 🐙 Async GitHub API
├── token_manager.py        # 🔑 Async token rotation
├── proxy_manager.py        # 🌐 Async proxy scraping
└── proxy_refresher.py      # 🔄 Background maintenance

🚀 Performance Comparison

<div align="center"> <table> <thead> <tr> <th>Metric</th> <th>Standard</th> <th>High-Performance</th> <th>Improvement</th> </tr> </thead> <tbody> <tr> <td><b>PR Speed</b></td> <td>1-2 PRs/min</td> <td>30-50 PRs/min</td> <td><span style="color:#2ecc71">⬆️ 25x faster</span></td> </tr> <tr> <td><b>Concurrency</b></td> <td>Single-thread</td> <td>10-50 workers</td> <td><span style="color:#2ecc71">⬆️ 50x</span></td> </tr> <tr> <td><b>Token Rotation</b></td> <td>Manual</td> <td>Automatic</td> <td><span style="color:#2ecc71">✨ Smart</span></td> </tr> <tr> <td><b>Proxy Support</b></td> <td>Static list</td> <td>Auto-fetch + test</td> <td><span style="color:#2ecc71">✨ Dynamic</span></td> </tr> <tr> <td><b>Rate Limit</b></td> <td>Cached</td> <td>Live API checks</td> <td><span style="color:#2ecc71">✨ Real-time</span></td> </tr> <tr> <td><b>Memory Usage</b></td> <td>~50 MB</td> <td>~300-500 MB</td> <td><span style="color:#f39c12">⬆️ 6-10x</span></td> </tr> </tbody> </table> </div>

📊 Real-World Performance

Test: 1000 PRs with High-Performance Modules

bash
python parallel_automation.py --count 1000 --concurrent 20

</div>

Results:

⏱️  Time: 16 minutes (vs 8+ hours sequential)
✅ Success Rate: 94%
📈 Speed: 62.5 PRs/min
🔄 Token Rotation: 3 tokens cycled automatically
🌐 Proxies Used: 87 working proxies
💾 Memory: ~720 MB peak

⚡1️⃣ HighPerformanceGitManager

🎯 Key Features:

python
# Windows-compatible async Git operations
async def sync_base(self) -> bool:
    """Fast sync with depth=1 optimization"""
    
async def create_branch(self, name: str) -> bool:
    """Async branch creation"""
    
async def commit(self, file: str, message: str, content: str) -> bool:
    """Single-operation async commit"""
    
async def push(self, branch: str) -> bool:
    """Non-blocking push"""

🪟 Windows Optimization:

python
# Thread pool prevents blocking
self.executor = ThreadPoolExecutor(max_workers=10)

# Run git ops in executor
loop = asyncio.get_event_loop()
result = await loop.run_in_executor(
    self.executor,
    lambda: git_operation()
)

⚡2️⃣ HighPerformanceGitHubTool

🎯 Key Features:

Semaphore Control: Limit concurrent API calls
Smart Token Selection: Auto-switch on rate limits
Proxy Integration: Built-in proxy support

python
# Concurrency control
self.semaphore = asyncio.Semaphore(50)  # Max 50 concurrent

async with self.semaphore:
    process = await asyncio.create_subprocess_exec(...)

⚡3️⃣ HighPerformanceTokenManager

🎯 Key Features:

Real-Time Rate Limits: Live API checks every 5 minutes
Fair Distribution: Shuffle tokens for balanced usage
Auto-Refresh: Update stale token status

python
# Live rate limit check
async def check_token_rate_limit_async(self, token):
    headers = {'Authorization': f"token {token['token']}"}
    async with session.get('https://api.github.com/rate_limit', headers=headers):
        # Get real-time remaining count
        return remaining, reset_time

⚡4️⃣ HighPerformanceProxyManager

🎯 Proxy Sources:

python
sources = [
    # HTML Table Sources
    'https://free-proxy-list.net/',
    'https://www.sslproxies.org/',
    
    # API/Raw Sources (More Reliable)
    'https://api.proxyscrape.com/v2/',
    'https://raw.githubusercontent.com/TheSpeedX/PROXY-List/master/http.txt',
    'https://raw.githubusercontent.com/clarketm/proxy-list/master/proxy-list-raw.txt'
]

🧪 Concurrent Testing:

python
# Test 50 proxies simultaneously
semaphore = asyncio.Semaphore(50)

async def limited_test(proxy):
    async with semaphore:
        return await self.test_proxy(proxy)

# Parallel execution
results = await asyncio.gather(*[limited_test(p) for p in proxies])

⚡ Latency-Based Sorting:

python
# Sort by speed (fastest first)
working_proxies.sort(key=lambda x: x.get("latency", 999))

⚡5️⃣ ProxyRefresher

🎯 Background Service

bash
# Run in separate terminal
python -m high_performance.proxy_refresher

Output:

🔄 Proxy Refresher Started
⏰ Will refresh proxies every 30 minutes

[10:00:00] Refreshing proxies...
  🔎 Fetching from free-proxy-list...
  🔎 Fetching from proxyscrape...
  📦 Collected: 342 unique proxies
  📦 Testing: 342 proxies...
  ✅ Working: 87 proxies

[10:30:00] Refreshing proxies...
...

🔐 Security & Best Practices

🛡️ Keep Your Tokens Safe

🔒 Token Security Checklist

<table> <tr> <td>✅</td> <td><b>Never commit tokens to Git</b></td> <td>Add to <code>.gitignore</code></td> </tr> <tr> <td>✅</td> <td><b>Use environment variables</b></td> <td><code>export GITHUB_TOKEN="ghp_xxx"</code></td> </tr> <tr> <td>✅</td> <td><b>Rotate tokens regularly</b></td> <td>Every 30-90 days</td> </tr> <tr> <td>✅</td> <td><b>Use fine-grained tokens</b></td> <td>Limit scope to specific repos</td> </tr> <tr> <td>✅</td> <td><b>Enable 2FA</b></td> <td>Extra security layer</td> </tr> <tr> <td>✅</td> <td><b>Monitor token usage</b></td> <td><code>gh api rate_limit</code></td> </tr> </table>

🛡️ API Rate Limits

GitHub Limits:

Authentication	Requests/Hour	Notes
Unauthenticated	60	Very limited
OAuth Token	5,000	Per token
GitHub App	15,000	Enterprise
Multiple Tokens	15,000+	Rotation

</div>

📊 Rate Limit Strategies:

python
# 1️⃣ Token Rotation
token = token_manager.get_best_token()

# 2️⃣ Monitor Limits
rate_info = gh.check_rate_limit()
if rate_info["remaining"] < 100:
    time.sleep(wait_time)

# 3️⃣ Exponential Backoff
for attempt in range(max_retries):
    try:
        result = api_call()
        break
    except RateLimitError:
        time.sleep(2 ** attempt)

🌐 Proxy Best Practices

<details> <summary><b>🆓 Free vs 💰 Paid Proxies</b></summary>

Feature	Free	Paid
Reliability	⭐⭐ (20-30%)	⭐⭐⭐⭐⭐ (99%+)
Speed	Slow	Fast
Security	⚠️ Questionable	✅ Verified
Support	None	24/7
Cost	$0	$10-200/mo
Best For	Testing	Production

💰 Recommended Paid Services:

Bright Data - Enterprise ($500+/mo)
Smartproxy - Balanced ($75/mo)
Oxylabs - Premium ($300/mo)
Proxy-Cheap - Budget ($10/mo)

</details>

🐛 Troubleshooting

🔧 Common Issues & Solutions

❌ Issue 1: "gh: command not found"

<details> <summary><b>📋 Problem Description</b></summary>

GitHub CLI is not installed or not in PATH.

</details> <details> <summary><b>✅ Solution</b></summary>

bash
# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt update && sudo apt install gh -y

# Windows
winget install --id GitHub.cli

# Verify
gh --version

</details>

❌ Issue 2: "Authentication failed"

<details> <summary><b>📋 Problem Description</b></summary>

GitHub CLI not authenticated or token expired.

</details> <details> <summary><b>✅ Solution</b></summary>

bash
# Re-authenticate
gh auth login

# Or use token directly
echo "YOUR_TOKEN" | gh auth login --with-token

# Verify authentication
gh auth status

</details>

❌ Issue 3: "API rate limit exceeded"

<details> <summary><b>📋 Problem Description</b></summary>

Too many API requests in short time.

</details> <details> <summary><b>✅ Solutions</b></summary>

Option 1: Add More Tokens

json
{
  "tokens": [
    {"name": "Token 1", "token": "ghp_xxx1"},
    {"name": "Token 2", "token": "ghp_xxx2"},
    {"name": "Token 3", "token": "ghp_xxx3"}
  ]
}

Option 2: Check Rate Limit

bash
gh api rate_limit

# Output shows:
# - Remaining requests
# - Reset time

Option 3: Increase Delay

json
{
  "delay_seconds": 60
}

</details>

❌ Issue 4: "Failed to push branch"

<details> <summary><b>📋 Problem Description</b></summary>

Git push fails due to network or permissions.

</details> <details> <summary><b>✅ Solutions</b></summary>

Check 1: Internet Connection

bash
ping github.com

Check 2: Repository Permissions

bash
gh repo view --web
# Verify you have write access

Check 3: Branch Protection

bash
gh api repos/OWNER/REPO/branches/main/protection

Check 4: Re-authenticate

bash
gh auth refresh

</details>

❌ Issue 5: "No changes to commit"

<details> <summary><b>📋 Problem Description</b></summary>

File already contains identical content.

</details> <details> <summary><b>✅ Solutions</b></summary>

Solution 1: Reset State

bash
python main.py --reset

Solution 2: Change Target File

json
{
  "readme_file": "CONTRIBUTING.md"
}

Solution 3: Force Content Change
Add timestamps or unique IDs to each commit.

</details>

🔍 Enable Debug Mode

bash
# Set environment variable
export LOG_LEVEL=DEBUG

# Run with debug logging
python main.py

# Or edit logger.py
logger.setLevel(logging.DEBUG)

Debug Output Example:

DEBUG - Token selected: primary (4850 remaining)
DEBUG - Proxy selected: http://8.219.97.248:9090
DEBUG - Executing: git push origin automation-1-abc123
DEBUG - Command output: [SUCCESS]
DEBUG - API response: {"pr_number": 12345}

📈 Performance Tips

⚡ Maximize Your Speed

🚀 Speed Optimization Matrix

<table> <thead> <tr> <th>Strategy</th> <th>Impact</th> <th>Difficulty</th> <th>Implementation</th> </tr> </thead> <tbody> <tr> <td><b>Use Parallel Mode</b></td> <td>⭐⭐⭐⭐⭐</td> <td>🟢 Easy</td> <td><code>python parallel_automation.py --concurrent 20</code></td> </tr> <tr> <td><b>Multiple Tokens</b></td> <td>⭐⭐⭐⭐⭐</td> <td>🟢 Easy</td> <td>Add 2-3 tokens to <code>github_tokens.json</code></td> </tr> <tr> <td><b>Enable Proxies</b></td> <td>⭐⭐⭐⭐</td> <td>🟡 Medium</td> <td>Set <code>"use_free_proxies": true</code></td> </tr> <tr> <td><b>Reduce Delay</b></td> <td>⭐⭐⭐</td> <td>🟢 Easy</td> <td><code>--delay 10</code> (sequential mode)</td> </tr> <tr> <td><b>Skip Auto-Merge</b></td> <td>⭐⭐</td> <td>🟢 Easy</td> <td><code>--no-merge</code></td> </tr> <tr> <td><b>Use SSD Storage</b></td> <td>⭐⭐</td> <td>🔴 Hard</td> <td>Run on SSD drive</td> </tr> </tbody> </table>

💾 Resource Optimization

Optimal Settings by Hardware:

System Specs	Workers	Memory	PRs/Hour	Recommended
2 CPU, 4GB RAM	5	~150 MB	~900	🟢 Basic
4 CPU, 8GB RAM	10	~300 MB	~1,800	🟢 Good
8 CPU, 16GB RAM	20	~600 MB	~3,600	🟡 Great
16 CPU, 32GB RAM	40	~1.2 GB	~7,200	🔴 Overkill

</div>

📊 Monitor Resources:

bash
# CPU & Memory Usage
top -p $(pgrep -f parallel_automation)

# Disk I/O
iotop -p $(pgrep -f parallel_automation)

# Network Stats
nethogs

📊 Benchmarks

<details> <summary><b>Test 1: Sequential Mode (100 PRs)</b></summary>

Configuration:

json
{
  "pr_count": 100,
  "delay_seconds": 30,
  "auto_merge": true
}

Results:

⏱️  Time: 52 minutes
✅ Success: 98 PRs (98%)
❌ Failed: 2 PRs (2%)
🔁 Retries: 3 operations
💾 Memory: ~50 MB
📈 Speed: 1.9 PRs/min

</details> <details> <summary><b>Test 2: Parallel Mode (1000 PRs, 10 workers)</b></summary>

Configuration:

bash
python parallel_automation.py --count 1000 --concurrent 10

Results:

⏱️  Time: 28 minutes
✅ Success: 960 PRs (96%)
❌ Failed: 40 PRs (4%)
🔁 Retries: 42 operations
💾 Memory: ~380 MB
📈 Speed: 35.7 PRs/min

</details> <details> <summary><b>Test 3: Maximum Speed (1000 PRs, 20 workers, 3 tokens)</b></summary>

Configuration:

bash
python parallel_automation.py --count 1000 --concurrent 20

Results:

⏱️  Time: 16 minutes
✅ Success: 940 PRs (94%)
❌ Failed: 60 PRs (6%)
🔁 Retries: 68 operations
💾 Memory: ~720 MB
📈 Speed: 62.5 PRs/min
🔄 Tokens: 3 rotated
🌐 Proxies: 87 used

</details>

🤝 Contributing

💪 Join the Community

🚀 How to Contribute

bash
# 1️⃣ Fork the repository
gh repo fork itxashancode/Pull-Shark-Automation

# 2️⃣ Clone your fork
git clone https://github.com/YOUR_USERNAME/Pull-Shark-Automation.git
cd Pull-Shark-Automation

# 3️⃣ Create feature branch
git checkout -b feature/amazing-feature

# 4️⃣ Make your changes
# ... edit files ...

# 5️⃣ Commit with conventional commits
git commit -m "feat: add amazing feature"

# 6️⃣ Push to your fork
git push origin feature/amazing-feature

# 7️⃣ Create Pull Request
gh pr create --title "Add amazing feature" --body "Description..."

📝 Code Style Guide

python
# ✅ Good - Clear, documented, typed
def create_pull_request(title: str, body: str, head: str) -> Optional[str]:
    """
    Create a pull request via GitHub CLI.
    
    Args:
        title: PR title
        body: PR description
        head: Source branch name
        
    Returns:
        PR number as string, or None if failed
    """
    try:
        result = gh_tool.create_pr(title, body, head)
        return result
    except Exception as e:
        logger.error(f"Failed to create PR: {e}")
        return None

# ❌ Bad - Unclear, no types, no docs
def createPR(t,b,h):
    result=gh_tool.create_pr(t,b,h)
    return result

🎨 Formatting Tools:

bash
# Auto-format with black
black *.py

# Check style with flake8
flake8 *.py

# Type checking with mypy
mypy *.py

🐛 Reporting Bugs

Found a bug? Help us fix it!

Steps:

Check existing issues
Create new issue with template
Include:
- OS & Python version
- Full error message
- Steps to reproduce
- Expected vs actual behavior

💡 Suggesting Features

Have an idea? We'd love to hear it!

Steps:

Check existing discussions
Open feature request
Describe:
- Use case
- Proposed solution
- Alternatives considered

📄 License

MIT License

MIT License

Copyright (c) 2026 Pull Shark Automation

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

</div>

🙏 Acknowledgments

🌟 Built With Amazing Tools

💖 Special Thanks

GitHub - For excellent CLI and API
Python Community - For amazing async libraries
Contributors - Everyone who improved this project
You - For using Pull Shark Automation!

📞 Support & Community

⭐ Star History

</div>

🎉 Final Words

🦈 Unleash the Pull Shark! 🦈

If this tool helped you earn your Pull Shark badge, please ⭐ star the repository!

<p> <i>Made with ❤️ by developers, for developers</i> </p> <p> <a href="#-github-pull-shark-automation">⬆️ Back to Top</a> </p> <p> <img src="https://komarev.com/ghpvc/?username=itxashancode&label=Repository%20Views&color=0e75b6&style=flat" alt="Repository Views"/> </p>

⚠️ Remember: This tool is for educational purposes. Use responsibly and follow GitHub's Terms of Service.

</div>

Contributors

Showing top 1 contributor by commit count.

itxashancode

27 commits

View all contributors on GitHub →

This article is auto-generated from itxashancode/Pull-Shark-Automation via the GitHub API.Last fetched: 6/13/2026

🦈 GitHub Pull Shark Automation

⚠️ Educational Purpose Only

🏆 Earn Your Pull Shark Badge

🎯 What Is Pull Shark Automation?

📑 Table of Contents

🌟 Features

🎯 Core Capabilities

🔧 Advanced Features

🎬 How It Works

🏗️ Architecture

System Design Overview

🔑 Component Matrix

📦 Installation

🚀 Quick Start Guide

Prerequisites Checklist

Step 1️⃣: Clone Repository

Step 2️⃣: Install Dependencies

Step 3️⃣: Install GitHub CLI

Step 4️⃣: Authenticate GitHub

✅ Installation Complete!

⚙️ Configuration

🎛️ Setup Your Automation

📋 File 1: Main Config (config.json)

🔑 File 2: GitHub Tokens (github_tokens.json)

🌐 File 3: Proxies (proxies.txt)

🔔 Optional: Webhook Setup

✅ Configuration Complete!

🚀 Usage

🎮 Command Center

🏁 Quick Start Commands

📘 Sequential Mode (main.py)

⚡ Parallel Mode (parallel_automation.py)

📚 Usage Examples

💡 Pro Tips

🔧 Components Deep Dive

🏗️ System Architecture Breakdown

1️⃣ GitManager (git_manager.py)

2️⃣ GitHubTool (github_tool.py)

3️⃣ TokenManager (token_manager.py)

4️⃣ ProxyManager (proxy_manager.py)

5️⃣ Notifier (notifier.py)

6️⃣ Logger (logger.py)

⚡ High-Performance Modules

🚀 Turbocharged Async Implementation

📁 Module Structure

🚀 Performance Comparison

📊 Real-World Performance

⚡1️⃣ HighPerformanceGitManager

⚡2️⃣ HighPerformanceGitHubTool

⚡3️⃣ HighPerformanceTokenManager

⚡4️⃣ HighPerformanceProxyManager

⚡5️⃣ ProxyRefresher

🔐 Security & Best Practices

🛡️ Keep Your Tokens Safe

🔒 Token Security Checklist

🛡️ API Rate Limits

🌐 Proxy Best Practices

🐛 Troubleshooting

🔧 Common Issues & Solutions

❌ Issue 1: "gh: command not found"

❌ Issue 2: "Authentication failed"

❌ Issue 3: "API rate limit exceeded"

❌ Issue 4: "Failed to push branch"

❌ Issue 5: "No changes to commit"

🔍 Enable Debug Mode

📈 Performance Tips

⚡ Maximize Your Speed

🚀 Speed Optimization Matrix

💾 Resource Optimization

📊 Benchmarks

🤝 Contributing

💪 Join the Community

🚀 How to Contribute

📝 Code Style Guide

🐛 Reporting Bugs

💡 Suggesting Features

📄 License

MIT License

🙏 Acknowledgments

🌟 Built With Amazing Tools

📋 File 1: Main Config (`config.json`)

🔑 File 2: GitHub Tokens (`github_tokens.json`)

🌐 File 3: Proxies (`proxies.txt`)

📘 Sequential Mode (`main.py`)

⚡ Parallel Mode (`parallel_automation.py`)

1️⃣ GitManager (`git_manager.py`)

2️⃣ GitHubTool (`github_tool.py`)

3️⃣ TokenManager (`token_manager.py`)

4️⃣ ProxyManager (`proxy_manager.py`)

5️⃣ Notifier (`notifier.py`)

6️⃣ Logger (`logger.py`)