-[English](#english) | [中文](#chinese)
+
-
+# GenericAgent
-A minimalist autonomous agent framework that gives any LLM physical-level control over your PC — browser, terminal, file system, keyboard, mouse, screen vision, and mobile devices — in ~3,300 lines of Python.
+**A Minimal, Self-Evolving Autonomous Agent Framework**
-No Electron. No Docker. No Mac Mini. No 500K-line codebase. No paid installation service.
+*~3K lines of seed code · 9 atomic tools · ~100-line Agent Loop*
-## See It in Action
+
-
-
-
"Order me a milk tea" — navigates a delivery app, picks items, and checks out. |
-
"Find GEM stocks with EXPMA golden cross, turnover > 5%" — quantitative screening via mootdx. |
-
-
+
+
+
+
+
+
+
+
+ 
+
+
+**[English](#-english) · [中文](#-中文)**
+
+
-
-
Autonomous web exploration — browses and summarizes on its own schedule. |
-
"Find expenses over ¥2K in the past 3 months" — drives Alipay on a phone via ADB. |
-
WeChat batch messaging — yes, it can drive WeChat too. |
-
+
+ | 🛡️ Real-Browser CAPTCHA Survival |
+ 🌐 Autonomous Web Exploration |
+
+
+  |
+ |
+
+
+ | While configuring a Discord bot, an hCaptcha "Are you human?" challenge pops up mid-task — GA's real browser session passes it and the task continues. See Browser Realness. |
+ Autonomously browses and periodically summarizes web content. |
+
+
+ | 🧋 Food Delivery Order |
+ 📈 Quantitative Stock Screening |
+
+
+ |
+ |
+
+
+ | "Order me a milk tea" — navigates the delivery app, selects items, completes checkout. |
+ "Find GEM stocks with EXPMA golden cross, turnover > 5%" — quantitative screening. |
+
+
+ | 💰 Expense Tracking |
+ 💬 Batch Messaging |
+
+
+ |
+ |
+
+
+ | "Find expenses over ¥2K in the last 3 months" — drives Alipay via ADB. |
+ Sends bulk WeChat messages, fully driving the WeChat client. |
+
-## What Happens When You Use It
+---
+
+## 🚀 Quick Start
+
+> ⚠️ **Python version**: use **Python 3.11 or 3.12**. **Do not** use Python 3.14 — it is incompatible with `pywebview` and a few other GA dependencies.
+>
+> 📖 Detailed installation guide: **[installation.md](docs/installation.md)** · **[installation_zh.md（中文）](docs/installation_zh.md)**
+### For LLM Agents
+
+Fetch the installation guide and follow it:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md
```
-You: "Read my WeChat messages"
-Agent: installs dependencies → reverse-engineers DB → writes reader script → saves as SOP
-Next time: instant recall, zero setup.
-You: "Monitor stock prices and alert me"
-Agent: installs mootdx → builds screening workflow → sets up scheduled task → saves as SOP
-Next time: one sentence to run.
+### For Humans
+
+#### Method 1 — Clone & install *(recommended)*
-You: "Send this file via Gmail"
-Agent: configures OAuth → writes send script → saves as SOP
-Next time: just works.
+```bash
+git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent
+uv venv && uv pip install -e ".[ui]"
+cp mykey_template_en.py mykey.py # fill in your LLM API key
```
-**Dogfooding**: This repository — from installing Git to `git init`, writing this README, to every commit message — was built entirely by GenericAgent without the author opening a terminal once.
+Dependencies are deliberately tiered: the agent core needs only `requests`, plus four lightweight packages (`beautifulsoup4`, `bottle`, `simple-websocket-server`, `aiohttp`) for TMWebdriver's local server. The `[ui]` extra pulls in frontend libraries (Streamlit, `prompt_toolkit`/`rich` for the TUI, …) — install it for the bundled UIs, or skip it entirely and drive the agent headless. No Playwright, no LangChain, no browser binaries to download.
-Every task the agent solves becomes a permanent skill. After a few weeks, your instance has a unique skill tree — grown entirely from 3,300 lines of seed code.
+Then launch:
-## The Seed Philosophy
+```bash
+python frontends/tui_v3.py # Terminal UI (recommended)
+python launch.pyw # Streamlit web UI
+```
-Most agent frameworks ship as finished products. GenericAgent ships as a **seed**.
+#### Method 2 — One-line installer *(convenience)*
-The 5 core SOPs define how the agent thinks, remembers, and operates. From there, every new capability is discovered and recorded by the agent itself:
+Sets up a self-contained directory with an isolated Python environment, Git, and a ready-to-run package. The script is in [`assets/`](assets/) if you'd like to read it first.
-1. You ask it to do something new
-2. It figures out how (install dependencies, write scripts, test)
-3. It saves the procedure as a new SOP in its memory
-4. Next time, it recalls and executes directly
+**Windows PowerShell**
-The agent doesn't just execute — it **learns and remembers**.
+```powershell
+powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.ps1 | iex"
+```
-## Quick Start
+**Linux / macOS**
```bash
-# 1. Clone
-git clone https://github.com/lsdefine/pc-agent-loop.git
-cd pc-agent-loop
+GLOBAL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga_install.sh)"
+```
+
+> 💡 GenericAgent grows its environment **through the Agent itself** — don't pre-install everything. See [Unlocking Advanced Capabilities](#-unlocking-advanced-capabilities) below.
-# 2. Install minimal deps
-pip install streamlit pywebview
+---
-# 3. Configure API key
-cp mykey_template.py mykey.py
-# Edit mykey.py with your LLM API key
+## 💻 Usage
-# 4. Launch
-python launch.pyw
-```
+### Frontends
-**Also runs on Android** — tested successfully on Termux with `python agentmain.py` (CLI frontend):
+#### Terminal UI *(recommended)*
+
+A lightweight, scrollback-first terminal interface built on `prompt_toolkit` + `rich`. Supports multiple concurrent sessions and real-time streaming.
```bash
-# In Termux
-cd /sdcard/ga
-python agentmain.py
+python frontends/tui_v3.py
```
-Once running, tell the agent: *"Execute web setup SOP to unlock browser tools"* — it handles the rest. See [WELCOME_NEW_USER.md](WELCOME_NEW_USER.md) for the full bootstrap sequence.
+
+ 
