threads-cleaner 0.2.0__tar.gz

threads_cleaner-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+.ruff_cache/
+dist/
+*.egg-info/

threads_cleaner-0.2.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: threads-cleaner
+Version: 0.2.0
+Summary: Bulk-delete your Threads posts and replies. Free, open-source, runs locally.
+Project-URL: Homepage, https://github.com/vincentmathis/threads-cleaner
+Project-URL: Repository, https://github.com/vincentmathis/threads-cleaner
+Author-email: Vince <vince@example.com>
+License: MIT
+Keywords: browser-automation,bulk,cleaner,delete,threads
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: playwright>=1.59.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# threads-cleaner
+
+Bulk-delete your Threads posts and replies via browser automation.  
+Clicks the web UI like a human — no API keys, no developer account, no rate limits.
+
+## Installation
+
+```bash
+pip install threads-cleaner
+# or
+uv add threads-cleaner
+```
+
+Then install the Playwright browser:
+
+```bash
+playwright install chromium
+# or
+uv run playwright install chromium
+```
+
+## Quick start
+
+```bash
+# 1. Log in (opens a browser — go to threads.net, sign in, navigate to your profile)
+threads-cleaner browser-login
+
+# 2. Delete all posts
+threads-cleaner browser-delete
+
+# 3. Show the browser window to watch what happens
+threads-cleaner browser-delete --headed --max 5
+```
+
+## Usage
+
+| Command | Description |
+|---------|-------------|
+| `browser-login` | Opens a headed browser — log into Threads and session is saved automatically |
+| `browser-delete` | Deletes posts by clicking the Threads UI |
+| `browser-delete --include-replies` | Also delete your replies |
+| `browser-delete --max N` | Stop after N deletions (0 = unlimited) |
+| `browser-delete --dry-run` | Open browser, navigate to profile, but don't confirm any deletes |
+| `browser-delete --headed` | Show the browser (useful for debugging) |
+| `browser-delete --yes` | Skip the confirmation prompt (for scripting) |
+
+### Examples
+
+```bash
+# Delete up to 10 posts, show the browser
+threads-cleaner browser-delete --headed --max 10
+
+# Delete everything including replies, no prompts
+threads-cleaner browser-delete --include-replies --yes
+
+# Preview what the tool would do
+threads-cleaner browser-delete --dry-run --headed
+
+# Delete 50 replies only
+threads-cleaner browser-delete --include-replies --max 50
+```
+
+## How it works
+
+1. **`browser-login`** opens a Chromium window — you sign into threads.net and the session cookies are saved locally.
+2. **`browser-delete`** loads those cookies into a fresh browser, navigates to your profile, and for each post:
+   - Clicks the **More** (⋮) button
+   - Clicks **Delete** in the popup menu
+   - Clicks **Delete** in the confirmation dialog
+3. With `--include-replies`, it also navigates to `/replies/` and repeats the same loop.
+
+Each delete takes ~3-4 seconds (limited by UI animations).  
+The tool scrolls down automatically as it runs, so it can delete hundreds of items in one session.
+
+### Safety
+
+- **`--dry-run`** opens the browser and navigates to your profile but never clicks anything destructive.
+- **`--max N`** stops after N successful deletes.
+- If a "Something went wrong" toast appears, the tool counts it as a failure (not a success) and continues.
+- Session cookies expire — re-run `browser-login` if you get a login error.
+
+## Requirements
+
+- Python 3.11+
+- Chromium (installed via `playwright install chromium`)
+
+## Why no API?
+
+Meta's Threads Graph API requires an approved Facebook Developer account (the author's was suspended).  
+The Instagram REST API endpoints that Threads used internally are now returning 404 or killing sessions.  
+The only reliable approach is real browser automation that clicks the UI like a human.
+
+## License
+
+MIT

threads_cleaner-0.2.0/README.md

@@ -0,0 +1,95 @@
+# threads-cleaner
+
+Bulk-delete your Threads posts and replies via browser automation.  
+Clicks the web UI like a human — no API keys, no developer account, no rate limits.
+
+## Installation
+
+```bash
+pip install threads-cleaner
+# or
+uv add threads-cleaner
+```
+
+Then install the Playwright browser:
+
+```bash
+playwright install chromium
+# or
+uv run playwright install chromium
+```
+
+## Quick start
+
+```bash
+# 1. Log in (opens a browser — go to threads.net, sign in, navigate to your profile)
+threads-cleaner browser-login
+
+# 2. Delete all posts
+threads-cleaner browser-delete
+
+# 3. Show the browser window to watch what happens
+threads-cleaner browser-delete --headed --max 5
+```
+
+## Usage
+
+| Command | Description |
+|---------|-------------|
+| `browser-login` | Opens a headed browser — log into Threads and session is saved automatically |
+| `browser-delete` | Deletes posts by clicking the Threads UI |
+| `browser-delete --include-replies` | Also delete your replies |
+| `browser-delete --max N` | Stop after N deletions (0 = unlimited) |
+| `browser-delete --dry-run` | Open browser, navigate to profile, but don't confirm any deletes |
+| `browser-delete --headed` | Show the browser (useful for debugging) |
+| `browser-delete --yes` | Skip the confirmation prompt (for scripting) |
+
+### Examples
+
+```bash
+# Delete up to 10 posts, show the browser
+threads-cleaner browser-delete --headed --max 10
+
+# Delete everything including replies, no prompts
+threads-cleaner browser-delete --include-replies --yes
+
+# Preview what the tool would do
+threads-cleaner browser-delete --dry-run --headed
+
+# Delete 50 replies only
+threads-cleaner browser-delete --include-replies --max 50
+```
+
+## How it works
+
+1. **`browser-login`** opens a Chromium window — you sign into threads.net and the session cookies are saved locally.
+2. **`browser-delete`** loads those cookies into a fresh browser, navigates to your profile, and for each post:
+   - Clicks the **More** (⋮) button
+   - Clicks **Delete** in the popup menu
+   - Clicks **Delete** in the confirmation dialog
+3. With `--include-replies`, it also navigates to `/replies/` and repeats the same loop.
+
+Each delete takes ~3-4 seconds (limited by UI animations).  
+The tool scrolls down automatically as it runs, so it can delete hundreds of items in one session.
+
+### Safety
+
+- **`--dry-run`** opens the browser and navigates to your profile but never clicks anything destructive.
+- **`--max N`** stops after N successful deletes.
+- If a "Something went wrong" toast appears, the tool counts it as a failure (not a success) and continues.
+- Session cookies expire — re-run `browser-login` if you get a login error.
+
+## Requirements
+
+- Python 3.11+
+- Chromium (installed via `playwright install chromium`)
+
+## Why no API?
+
+Meta's Threads Graph API requires an approved Facebook Developer account (the author's was suspended).  
+The Instagram REST API endpoints that Threads used internally are now returning 404 or killing sessions.  
+The only reliable approach is real browser automation that clicks the UI like a human.
+
+## License
+
+MIT

threads_cleaner-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "threads-cleaner"
+version = "0.2.0"
+description = "Bulk-delete your Threads posts and replies. Free, open-source, runs locally."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["threads", "delete", "bulk", "cleaner", "browser-automation"]
+authors = [
+    { name = "Vince", email = "vince@example.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "playwright>=1.59.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/vincentmathis/threads-cleaner"
+Repository = "https://github.com/vincentmathis/threads-cleaner"
+
+[project.scripts]
+threads-cleaner = "threads_cleaner.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/threads_cleaner"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/threads_cleaner"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.4.0",
+]

threads_cleaner-0.2.0/src/threads_cleaner/__main__.py

@@ -0,0 +1,3 @@
+from threads_cleaner.main import app
+
+app()

threads_cleaner-0.2.0/src/threads_cleaner/browser.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import time
+
+from rich.console import Console
+
+from threads_cleaner import config
+
+console = Console()
+
+
+class BrowserDeleter:
+    def __init__(self, session: dict, *, headed: bool = False):
+        self.session = session
+        self._headed = headed
+        self._browser = None
+        self._context = None
+        self._page = None
+        self._pw = None
+
+    def _cookies_for_playwright(self) -> list[dict]:
+        cookies = []
+        now_ts = int(time.time()) + 86400 * 30
+        for name in ("sessionid", "csrftoken", "ds_user_id", "rur"):
+            val = self.session.get(name, "")
+            if val:
+                for domain in (".threads.net", ".threads.com"):
+                    cookies.append({
+                        "name": name, "value": val,
+                        "domain": domain, "path": "/",
+                        "secure": True, "sameSite": "Lax",
+                        "expires": now_ts,
+                        **({"httpOnly": True} if name == "sessionid" else {}),
+                    })
+        return cookies
+
+    def start(self):
+        from playwright.sync_api import sync_playwright
+        self._pw = sync_playwright().start()
+        self._browser = self._pw.chromium.launch(
+            headless=not self._headed,
+            args=["--disable-blink-features=AutomationControlled", "--no-sandbox"],
+        )
+        self._context = self._browser.new_context(
+            viewport={"width": 1280, "height": 720},
+            user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
+        )
+        self._page = self._context.new_page()
+        console.print("[dim]  setting session cookies...[/]")
+        self._context.add_cookies(self._cookies_for_playwright())
+        self._page.goto("about:blank")
+
+    def stop(self):
+        if self._browser:
+            self._browser.close()
+        if self._pw:
+            self._pw.stop()
+
+    def _dismiss_popups(self):
+        try:
+            self._page.keyboard.press("Escape")
+            time.sleep(0.3)
+        except: pass
+        for text in ["Allow", "Accept", "Accept all", "Allow all", "Reject", "Close", "Got it"]:
+            try:
+                btn = self._page.locator(f'button:has-text("{text}")').first
+                if btn.is_visible(timeout=500):
+                    btn.click(timeout=1000)
+                    time.sleep(0.3)
+            except: pass
+        try:
+            self._page.evaluate("document.querySelectorAll('[role=dialog]').forEach(e=>e.remove()); document.body.style.overflow='';")
+        except: pass
+
+    def _find_and_click_more(self) -> bool:
+        return self._page.evaluate("""
+            (() => {
+                const icons = document.querySelectorAll('svg[aria-label="More"]');
+                for (const icon of icons) {
+                    if (icon.offsetParent === null) continue;
+                    if (icon.dataset.tried) continue;
+                    const r = icon.getBoundingClientRect();
+                    if (r.width < 5 || r.height < 5) continue;
+                    if (r.y < 100) continue;
+                    icon.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+                    return true;
+                }
+                return false;
+            })()
+        """)
+
+    def _click_menu_delete(self) -> bool:
+        return self._page.evaluate("""
+            (() => {
+                const menu = document.querySelector('[role="menu"]');
+                if (!menu) return false;
+                const all = menu.querySelectorAll('span, div, button, [role="button"]');
+                for (const el of all) {
+                    if (el.offsetParent === null) continue;
+                    const txt = el.innerText || el.textContent || '';
+                    if (txt.trim() === 'Delete' && el.childElementCount === 0) {
+                        el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+                        return true;
+                    }
+                }
+                // No Delete — this More belongs to someone else's post.
+                // Mark the first untried More SVG so we skip it next time.
+                const icons = document.querySelectorAll('svg[aria-label="More"]');
+                for (const icon of icons) {
+                    if (icon.offsetParent === null) continue;
+                    if (icon.dataset.tried) continue;
+                    const r = icon.getBoundingClientRect();
+                    if (r.width < 5 || r.height < 5) continue;
+                    if (r.y < 100) continue;
+                    icon.dataset.tried = '1';
+                    break;
+                }
+                return false;
+            })()
+        """)
+
+    def _click_confirm_delete(self) -> bool:
+        return self._page.evaluate("""
+            (() => {
+                const all = document.querySelectorAll('span, div, button, [role="button"]');
+                for (const el of all) {
+                    if (el.offsetParent === null) continue;
+                    const txt = el.innerText || el.textContent || '';
+                    if (txt.trim() === 'Delete' && el.childElementCount === 0) {
+                        if (el.closest('[role="dialog"]')) {
+                            el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+                            return true;
+                        }
+                    }
+                }
+                return false;
+            })()
+        """)
+
+    def _dismiss_toasts(self):
+        try:
+            self._page.keyboard.press("Escape")
+            time.sleep(0.4)
+            self._page.keyboard.press("Escape")
+            time.sleep(0.3)
+        except:
+            pass
+
+    def _has_error_toast(self) -> bool:
+        return self._page.evaluate("""
+            (() => {
+                const all = document.querySelectorAll('span, div, [role="alert"]');
+                for (const el of all) {
+                    const txt = (el.innerText || el.textContent || '').toLowerCase();
+                    if (txt.includes('something went wrong') || txt.includes('try again')) {
+                        return true;
+                    }
+                }
+                return false;
+            })()
+        """)
+
+    def _delete_next_item(self) -> bool:
+        self._dismiss_toasts()
+        if not self._find_and_click_more():
+            return False
+        time.sleep(0.8)
+        if not self._click_menu_delete():
+            self._page.keyboard.press("Escape")
+            time.sleep(0.3)
+            return False
+        time.sleep(0.8)
+        if not self._click_confirm_delete():
+            self._page.keyboard.press("Escape")
+            time.sleep(0.3)
+            return False
+        time.sleep(1.5)
+        had_error = self._has_error_toast()
+        self._dismiss_toasts()
+        if had_error:
+            return False
+        return True
+
+    def _delete_loop(self, label: str, max_deletes: int = 0) -> int:
+        deleted = 0
+        consecutive_fails = 0
+        total_fails = 0
+        while True:
+            if max_deletes and deleted >= max_deletes:
+                console.print(f"[dim]  hit limit of {max_deletes} {label}[/]")
+                break
+            ok = self._delete_next_item()
+            if ok:
+                deleted += 1
+                consecutive_fails = 0
+                total_fails = 0
+                if deleted % 10 == 0:
+                    console.print(f"[dim]  deleted {deleted} {label}...[/]")
+                continue
+            consecutive_fails += 1
+            total_fails += 1
+            if total_fails > 60:
+                console.print(f"[dim]  gave up after {total_fails} failures[/]")
+                break
+            if consecutive_fails >= 5:
+                before = self._page.evaluate("window.scrollY")
+                self._page.evaluate("window.scrollBy(0, 5000)")
+                time.sleep(2)
+                after = self._page.evaluate("window.scrollY")
+                if after == before:
+                    console.print(f"[dim]  reached end of {label}[/]")
+                    break
+                consecutive_fails = 0
+            else:
+                self._page.evaluate("window.scrollBy(0, 300)")
+                time.sleep(0.8)
+        return deleted
+
+    def delete_posts(self, max_deletes: int = 0) -> int:
+        username = self.session.get("username", "")
+        profile_url = f"https://www.threads.com/@{username}"
+        console.print(f"[dim]  navigating to {profile_url}...[/]")
+        try:
+            self._page.goto(profile_url, wait_until="domcontentloaded", timeout=60000)
+        except: pass
+        time.sleep(4)
+        if "login" in self._page.url.lower():
+            console.print(f"[red]Not logged in (current URL: {self._page.url}).[/]")
+            console.print("[yellow]Run [bold]threads-cleaner browser-login[/] to refresh the session.[/]")
+            raise RuntimeError("Session expired or invalid")
+        self._dismiss_popups()
+        return self._delete_loop("posts", max_deletes)
+
+    def delete_replies(self, max_deletes: int = 0) -> int:
+        username = self.session.get("username", "")
+        replies_url = f"https://www.threads.com/@{username}/replies/"
+        console.print(f"[dim]  navigating to {replies_url}...[/]")
+        try:
+            self._page.goto(replies_url, wait_until="domcontentloaded", timeout=30000)
+        except:
+            pass
+        time.sleep(4)
+        self._dismiss_popups()
+        return self._delete_loop("replies", max_deletes)
+
+def run_browser_delete(*, include_replies=False, max_deletes=None, dry_run=False, yes=False, headed=False):
+    session = config.load_session()
+    if not session:
+        raise RuntimeError("Not logged in. Run:  threads-cleaner browser-login")
+    targets = "posts" + (" + replies" if include_replies else "")
+    label = f" (max {max_deletes})" if max_deletes else ""
+    mode = "DRY RUN (no deletes)" if dry_run else "LIVE"
+    console.print("[bold]Threads Cleaner - Browser Delete[/bold]\n"
+                  f"  Mode: {mode}\n"
+                  f"  Targets: {targets}{label}\n")
+    if not dry_run and not yes:
+        result = console.input("[yellow]This will delete items. Continue? [y/N] [/]")
+        if result.lower() != "y": return
+    if dry_run:
+        console.print("[blue]Dry run — nothing was deleted.[/]")
+        return
+    deleter = BrowserDeleter(session=session, headed=headed)
+    try:
+        deleter.start()
+        total = 0
+        total += deleter.delete_posts(max_deletes or 0)
+        if include_replies:
+            remaining = (max_deletes - total) if max_deletes else 0
+            total += deleter.delete_replies(remaining)
+        console.print(f"\n[bold green]Done.[/] Deleted {total} item(s).")
+    finally:
+        deleter.stop()
+
+
+def run_browser_login() -> dict:
+    from playwright.sync_api import sync_playwright, TimeoutError as PwTimeout
+    console.print("[bold]Threads Cleaner - Browser Login[/bold]\n")
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch(headless=False, args=["--no-sandbox"])
+        ctx = browser.new_context(viewport={"width": 1280, "height": 800})
+        page = ctx.new_page()
+        page.goto("about:blank")
+        console.print("[yellow]Go to [bold]https://www.threads.net/[/bold] -> log in -> go to your profile -> wait[/]")
+        try:
+            page.wait_for_url("**/***@**", timeout=600000)
+        except PwTimeout:
+            browser.close()
+            raise RuntimeError("Login timed out")
+        time.sleep(2)
+        cookies_raw = ctx.cookies()
+        cookies = {c["name"]: c["value"] for c in cookies_raw if c["name"] in ("sessionid", "csrftoken", "ds_user_id", "rur")}
+        if not cookies.get("sessionid"):
+            browser.close()
+            raise RuntimeError("No session cookie")
+        sessionid = cookies["sessionid"]
+        csrftoken = cookies.get("csrftoken", "")
+        ds_user_id = cookies.get("ds_user_id", "")
+        cookies["sessionid"] = sessionid
+        cookies["csrftoken"] = csrftoken
+        cookies["ds_user_id"] = ds_user_id
+        # Extract username from the URL
+        username = page.url.split("/@")[-1].split("/")[0].split("?")[0]
+        user_id = ds_user_id or ""
+        session = {"sessionid": sessionid, "csrftoken": csrftoken, "ds_user_id": user_id, "rur": cookies.get("rur", ""), "user_id": user_id, "username": username}
+        config.save_session(session)
+        browser.close()
+    console.print(f"[green]Session saved.[/] Logged in as [bold]@{username}[/]")
+    return session

threads_cleaner-0.2.0/src/threads_cleaner/config.py

@@ -0,0 +1,23 @@
+import json
+from pathlib import Path
+
+# Session storage
+CONFIG_DIR = Path.home() / ".config" / "threads-cleaner"
+SESSION_FILE = CONFIG_DIR / "session.json"
+
+
+def save_session(data: dict) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    SESSION_FILE.write_text(json.dumps(data, indent=2))
+    SESSION_FILE.chmod(0o600)
+
+
+def load_session() -> dict | None:
+    if SESSION_FILE.exists():
+        return json.loads(SESSION_FILE.read_text())
+    return None
+
+
+def clear_session() -> None:
+    if SESSION_FILE.exists():
+        SESSION_FILE.unlink()

threads_cleaner-0.2.0/src/threads_cleaner/main.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from threads_cleaner.browser import run_browser_delete, run_browser_login
+
+app     = typer.Typer(help="Bulk-delete your Threads posts and replies via browser automation.")
+console = Console()
+
+
+@app.command()
+def browser_login():
+    """Log in via a browser window (no manual cookie copying)."""
+    try:
+        run_browser_login()
+        console.print("Run [bold]threads-cleaner browser-delete --headed[/] to test it.")
+    except Exception as e:
+        console.print(f"[red]Login failed:[/] {e}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def browser_delete(
+    include_replies: bool = typer.Option(
+        False, "--include-replies", help="Also delete replies from the Replies tab."
+    ),
+    max_deletes: Optional[int] = typer.Option(
+        None, "--max", "-m", help="Stop after deleting this many items (0 = unlimited)."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview without deleting."
+    ),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip the confirmation prompt."
+    ),
+    headed: bool = typer.Option(
+        False, "--headed", help="Show the browser window (for debugging)."
+    ),
+):
+    """Delete posts (and optionally replies) via a real browser (Playwright). Clicks the UI like a human."""
+    run_browser_delete(
+        include_replies=include_replies,
+        max_deletes=max_deletes,
+        dry_run=dry_run,
+        yes=yes,
+        headed=headed,
+    )
+
+
+if __name__ == "__main__":
+    app()