Metadata-Version: 2.4
Name: thunder-agent
Version: 0.4.0
Summary: Thunder — the human engine for AI agents: stealth browser body, human hands, TLS ghost, CAPTCHA bridge, and a stewmind thought layer.
Author-email: Emmanuel Ene Rejoice <emmanuelerogian723@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/emmanuelerogian723-alt/thunder
Project-URL: Powered by, https://huggingface.co/Erog0291/stewmind-1.7b
Keywords: ai-agents,browser-automation,stealth,mcp,anti-detection,human-like,scraping,stewmind
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: curl_cffi>=0.7
Requires-Dist: playwright>=1.40
Provides-Extra: mind
Requires-Dist: transformers>=4.44; extra == "mind"
Requires-Dist: torch; extra == "mind"
Provides-Extra: solver
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="site/assets/thunder-logo.png" width="220" alt="Thunder logo"/>

# ⚡ Thunder

**The human engine for AI agents.**

Give any software a human body: a real browser with a real fingerprint,
a mouse that trembles like a hand, keystrokes at human cadence, and a
TLS handshake indistinguishable from Chrome's.

*A bot that walks like a person.*

[![PyPI](https://img.shields.io/pypi/v/thunder-agent?color=%23ffd447&label=pypi%3A%20thunder-agent)](https://pypi.org/project/thunder-agent/)
[![Python](https://img.shields.io/badge/python-3.10%2B-3ddc84)](https://pypi.org/project/thunder-agent/)
[![License: MIT](https://img.shields.io/badge/license-MIT-4c8dff)](LICENSE)
[![Tests](https://img.shields.io/badge/stealth%20suite-passing-3ddc84)](tests/)

**[Install](#-install-in-30-seconds)** · **[Watch the proof](https://emmanuelerogian723-alt.github.io/thunder/)** · **[MCP for any software](#-mcp-give-any-software-a-human-body)**

</div>

---

## Why Thunder exists

Every anti-bot system on Earth looks for the same three tells:

1. *Protocol tells* — a Python scraper's TLS/HTTP-2 handshake screams "bot" before a byte of JS runs.
2. *Fingerprint tells* — `navigator.webdriver`, headless quirks, software-rendered WebGL, empty plugin arrays.
3. *Behavioral tells* — perfectly straight mouse paths, instant typing, zero reading pauses.

Thunder is a body for your AI that has **none of them**. Not patched over — *absent*, the way a real human's browser is.

```python
pip install thunder-agent
```

```python
import thunder

body = thunder.Body(profile="ada")          # a persistent human named Ada
await body.warmup()                         # age the session like a returning user
await body.go("https://protected-site.com")
await body.type("#email", "ada@example.com")   # typed like a person. Typos included.
await body.look("proof.png")                    # screenshot evidence
await body.rest()                              # close, keep the identity
```

Ada comes back tomorrow with the same cookies, same screen, same GPU string, same timezone. The site sees a returning regular.

---

## 📦 Install in 30 seconds

```bash
pip install thunder-agent
```

Works on Linux, macOS, Windows. Real-Chrome engine auto-detected; falls back to bundled Chromium.

```bash
thunder demo        # watch it browse like a human, right now
thunder ghost https://nowsecure.nl    # TLS-level fetch that passes the gate
```

---

## ⚡ The five layers

| Layer | What it does | The tell it kills |
|---|---|---|
| **Body** | Stealth browser: real Google Chrome, persistent profiles | headless shells, disposable identities |
| **Skin** | One consistent identity: UA, platform, GPU, screen, timezone, locale | fingerprint mismatches, `SwiftShader` WebGL |
| **Hand** | Bézier mouse with *hand tremor*, human keystroke cadence, typos it fixes | straight-line paths, machine-perfect timing |
| **Ghost** | Pure HTTP with Chrome's exact TLS/JA3 fingerprint + full header orchestration + human-style retries | Python-scrape handshake = instant 403 |
| **Pool** | Thunder's own proxy pool: auto-fetched, Ghost-validated egress, sticky per profile | shared/flagged datacenter IPs |
| **Warmup** | Organic light browsing before your target | cold first-hit sessions |

Verified live: `bot.sannysoft.com` under Thunder — **WebDriver missing (passed) · WebDriver Advanced passed · Chrome present (passed) · PluginArray passed** — *4 passed, 0 failed* with headed real Chrome. Ghost pulls a **200** from a Cloudflare gate that 403s plain Python, same minute.

---

## 🔌 MCP: give ANY software a human body

**Zero-install, zero-account — paste this URL into Claude** (Settings → Connectors → Add custom connector, or claude.ai/mcp):

```
https://thunder-mcp.onrender.com/mcp
```

That's it. No signup, no keys. Thunder-hosted, always on. You get `thunder_search`, `thunder_read`, `thunder_ghost`, `thunder_feel`, `thunder_solve`, `thunder_open` — search, clean extraction and bot-gate-safe fetches through Chrome's exact TLS handshake, from inside Claude.

Want the *full* human body (stealth Chrome, mouse tremor, human typing) under MCP? Run it locally — same 10-tool MCP server:

Thunder ships an MCP server (10 tools). Paste one config and Claude, Cursor, Cline, Windsurf — anything that speaks MCP — browses as a human:

```json
{ "mcpServers": { "thunder": {
    "command": "pipx", "args": ["run", "thunder-agent", "thunder-mcp"] } } }
```

```json
{ "mcpServers": { "thunder": {
    "command": "uvx", "args": ["--from", "thunder-agent", "thunder-mcp"] } } }
```

Tools: `thunder_open` · `thunder_read` · `thunder_search` · `thunder_click` · `thunder_type` · `thunder_scroll` · `thunder_ghost` · `thunder_solve` · `thunder_feel` · `thunder_close` — each one moves like a person, never like a script.

---

## 🚫 The blocker table — what used to stop bots, and Thunder's answer

| Blocker | Thunder's counter |
|---|---|
| Datacenter IP suspicion | `ProxyManager`: sticky per-profile residential proxies, health-checked, auto-rotation — `THUNDER_PROXY` env or `ProxyManager.from_env()` |
| No GPU / software WebGL | Full WebGL1 **and** WebGL2 spoof: vendor + renderer read as a real consumer GPU, on every API path detectors use |
| Headless leaks | Headless-evasion pack: `outerWidth/Height`, `colorDepth`, broken-image dimensions, full `window.chrome` shape, battery API |
| Advanced CAPTCHAs | Keyless `soft_solve` (human-hand click inside challenges) + `ocr_solve` (local OCR for image/math) + CapSolver/2Captcha bridge for the hardest |
| Behavioral ML | Hand tremor + micro-corrections + warmup sessions + thinking pauses — entropy that reads as a person, because it moves like one |

## 🔒 CAPTCHAs without a subscription

```python
from thunder.captcha import soft_solve, ocr_solve
result = await soft_solve(body.page)     # human-hand click, no keys needed
```

Non-interactive challenges often pass on a warmed-up session. For Turnstile/reCAPTCHA Enterprise, wire your own CapSolver or 2Captcha key — Thunder senses the challenge type and routes it.

---

## 🧠 Pair with any mind

Thunder is the body; bring any brain. Works with stewmind, Ollama, LM Studio, vLLM, OpenAI-compatible APIs, or fully offline transformers.

```python
from thunder.mind import Mind
mind = Mind(provider="ollama", model="llama3")
plan = await mind.think("find the pricing page and extract the tiers", body)
```

---

## 🧪 Tested, not promised

```bash
git clone https://github.com/emmanuelerogian723-alt/thunder
cd thunder && pip install -e ".[dev]" && pytest
```

Stealth regression suite: webdriver erased + scan-invisible · genuine PluginArray · headless pack · WebGL skin-consistency · proxy rotation. Each one fails loudly if a future commit breaks the human illusion.

---

## ⚖️ The honest limits (why people trust Thunder)

- No tool on Earth is "undetectable." Anyone selling that is lying to you.
- Cloud IPs still look like clouds — pair Thunder with a residential proxy for the hardest targets.
- Google-scale behavioral ML scores the whole session. Thunder's warmup + hand give you a real chance; it's not a magic key.
- **Use Thunder only where you're authorized.** Your accounts, your tests, your sites. That's the license, and it's the line.

MIT licensed. Built in the open — every claim on this page has a script in `tests/` or a screenshot in `proofs/`.

---

<div align="center">

**Watch Thunder beat the bot-detection gauntlet, live:**

**https://emmanuelerogian723-alt.github.io/thunder/**

⭐ If this saved you a month of anti-detect work, star the repo — it helps others find it.

*Thunder — built so software can finally act human.* 🌩️

</div>
