From a1f6c856964f03e9cf0b5739eabaabdedaed5ce3 Mon Sep 17 00:00:00 2001
From: "Ibrahim M. A. Nasser" <96ibman@gmail.com>
Date: Wed, 20 Aug 2025 19:54:41 +0200
Subject: [PATCH 1/2] feat: add --username single-check mode, init colorama,
 add timeout and UA; keep random scanning as default

---
 checker.py | 102 ++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 82 insertions(+), 20 deletions(-)

diff --git a/checker.py b/checker.py
index a80c818..0ebba4d 100644
--- a/checker.py
+++ b/checker.py
@@ -1,9 +1,13 @@
-import requests
+import argparse
 import random
+import string
 import time
-from colorama import Fore
+import requests
+from colorama import Fore, init as colorama_init
+
+colorama_init(autoreset=True)
 
-aqua = """
+AQUA = r"""
                                                                                                       
     ██╗  ██╗ ██████╗       ██╗   ██╗██╗  ██╗    
     ██║  ██║██╔═══██╗      ██║   ██║██║  ██║    
@@ -12,26 +16,84 @@
          ██║╚██████╔╝      ╚██████╔╝     ██║    
          ╚═╝ ╚══▀▀═╝        ╚═════╝      ╚═╝    
                                                                                              
---------------------------------------------------                                                                                                                                                                                                                                                                                
-    """
+--------------------------------------------------              ...
+"""
 
-print(Fore.BLUE + f"{aqua}" + Fore.RESET)
+SESSION = requests.Session()
+SESSION.headers.update({
+    "User-Agent": "github-username-availability-checker/0.1 (+https://github.com/4q-u4/GitHub-Username-Availability-Checker)"
+})
+TIMEOUT = 5.0
+PROFILE_URL = "https://www.github.com/{username}/"
+OUTPUT_FILE = "available2usernames.txt" 
 
+def check_username(username: str) -> str:
+    """Return 'taken', 'available', or 'unknown'."""
+    try:
+        resp = SESSION.get(PROFILE_URL.format(username=username), timeout=TIMEOUT)
+    except requests.RequestException:
+        return "unknown"
+    if resp.status_code == 200:
+        return "taken"
+    if resp.status_code == 404:
+        return "available"
+    return "unknown"
 
-while True:
-    user = ""
-    for character in random.choices("abcdefghijklmnopqrstuvwxyz123456789", k=3):
-        user = user + character
+def print_banner():
+    print(Fore.BLUE + AQUA + Fore.RESET)
 
-    response = requests.get(f"https://www.github.com/{user}/")
-
-    if response.status_code == 200:
-        print(Fore.RED + f"USERNAME TAKEN: {user}" + Fore.RESET)
-    elif response.status_code == 404:
-        print(Fore.GREEN + f"USERNAME AVAILABLE: {user}" + Fore.RESET)
-        # Append available usernames to a text file
-        with open("available2usernames.txt", "a") as file:
-            file.write(user + "\n")
+def handle_result(username: str, status: str):
+    if status == "taken":
+        print(Fore.RED + f"USERNAME TAKEN: {username}")
+        print(Fore.RED + f"https://github.com/{username}")
+    elif status == "available":
+        print(Fore.GREEN + f"USERNAME AVAILABLE: {username}")
+        try:
+            with open(OUTPUT_FILE, "a", encoding="utf-8") as f:
+                f.write(username + "\n")
+        except OSError:
+            print(Fore.YELLOW + "Could not write to output file.")
     else:
-        print("BLOCKED FROM GITHUB")
+        print(Fore.YELLOW + "Request blocked or unknown status. Backing off for 120 seconds...")
         time.sleep(120)
+
+def generate_random_username(length: int = 3) -> str:
+    alphabet = list(string.ascii_lowercase) + list("123456789")
+    return "".join(random.choice(alphabet) for _ in range(length))
+
+def run_random_loop(sleep_between: float = 0.2):
+    while True:
+        user = generate_random_username(3)
+        status = check_username(user)
+        handle_result(user, status)
+        time.sleep(sleep_between)
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Check GitHub username availability or scan randomly."
+    )
+    parser.add_argument(
+        "--username",
+        help="Check a specific username once. If omitted, runs the random scanner.",
+        type=str,
+    )
+    parser.add_argument(
+        "--sleep",
+        help="Delay in seconds between random checks. Default 0.2",
+        type=float,
+        default=0.2,
+    )
+    args = parser.parse_args()
+
+    print_banner()
+
+    if args.username:
+        name = args.username.strip()
+        status = check_username(name)
+        handle_result(name, status)
+        return
+
+    run_random_loop(sleep_between=args.sleep)
+
+if __name__ == "__main__":
+    main()

From 188fe9b31c9ef39df263761e565911fb710c58e9 Mon Sep 17 00:00:00 2001
From: "Ibrahim M. A. Nasser" <96ibman@gmail.com>
Date: Wed, 20 Aug 2025 20:00:15 +0200
Subject: [PATCH 2/2] docs: document --username option in usage section

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index 62ebfc0..6ad4a3f 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,18 @@ Run the script as described in the installation section.
 The script will generate random usernames and check their availability on GitHub.
 Available usernames will be saved to a text file named available_usernames.txt.
 
+
+### Check a specific username
+
+You can check a single, specific username instead of running the random scanner:
+
+```bash
+python checker.py --username 96ibman
+```
+
+- If the username is taken, the script prints the GitHub profile link.  
+- If the username is available, it prints "USERNAME AVAILABLE" and writes it to `available2usernames.txt`.  
+
 ### Contributing
 
 We welcome contributions to improve this project. To contribute, please follow these steps: