GenericAgent
A local autonomous-agent framework that turns completed work into reusable skills.
- Source repo
- lsdefine/GenericAgent
- Stars
- ★ 14k
- Last updated
- 2d ago
- License
- MIT
- Primary language
- Python
- FA score
- 32/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An individual who wants to build a Hacker News morning digest once, schedule it, and later invoke the retained workflow with a short instruction.
- Not a fit if
- Users unwilling to grant local file, shell, input, and ADB access
- Environments pinned to Python 3.14
- Source review
- 32/100 · Major gaps 6 safety controls not found
What does this agent do, and when should you use it?
GenericAgent is a self-evolving autonomous-agent framework for operating a local computer. The repository describes a roughly 3K-line seed codebase built around nine atomic tools and an approximately 100-line execution loop in agent_loop.py. Its layered memory stores rules, indexes, global facts, task Skills/SOPs, and session archives so completed task paths can be recalled for similar work. The project exposes terminal and Streamlit interfaces plus Telegram, Discord, and Lark/Feishu bot frontends; browser operations use TMWebdriver, a local WebSocket server paired with a Chrome extension for a persistent browser session. It fits users prepared to define boundaries around local file, shell, browser, and device access, and to let the agent progressively configure capabilities.
The agent cycles through environment perception, task reasoning, tool execution, and memory updates in agent_loop.py. Its documented atomic tools are code_run, file_read, file_write, file_patch, web_scan, web_execute_js, ask_user, update_working_checkpoint, and start_long_term_update. For a new task, it can use code_run to install dependencies, write and debug scripts, then store a reusable workflow in memory for later recall as a Skill. Web operations run through TMWebdriver: a local WebSocket server and Chrome extension act on a real persistent Chrome/Chromium session through web_scan and web_execute_js, retaining browser-session data such as login state. The repository also presents mobile-device operation through ADB and task submission through its bundled frontends.
- An individual who wants to build a Hacker News morning digest once, schedule it, and later invoke the retained workflow with a short instruction.
- An operations assistant who needs browser work performed in an already signed-in Chrome session, after setting up the documented web-automation capability.
- A technical user who wants an agent to read, write, patch, and execute local scripts while retaining a reusable SOP for the solved task.
- A mobile-workflow user who needs an ADB-driven task, such as locating Alipay expenses above a chosen threshold over the last three months.
- A small team or individual that wants to submit local automation tasks through a terminal, Streamlit UI, Telegram, Discord, or Lark/Feishu.
How do you install or deploy this agent?
Use Python 3.11 or 3.12; the repository says not to use Python 3.14. Clone and install:
git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent
uv venv && uv pip install -e ".[ui]"
cp mykey_template_en.py mykey.pyFill in an LLM API key in mykey.py. The [ui] extra installs the bundled UI dependencies; the repository says it can be omitted for headless operation.
How do you use this agent?
After configuring the API key, start the recommended terminal interface with python frontends/tui_v3.py, or the Streamlit interface with python launch.pyw. Documented IM entry points include python frontends/tgapp.py, python frontends/dcapp.py, and python frontends/fsapp.py. To enable web automation, instruct the agent: “Set up your web automation capability.” Then complete the documented manual step of dragging the bundled Chrome extension into chrome://extensions. OCR, vision, and computer-use capabilities are likewise enabled by asking the agent to perform the corresponding setup task.
What are this agent's strengths and limitations?
- The repository deliberately keeps the core small: about 3K lines, nine atomic tools, and an approximately 100-line Agent Loop.
- Its L0–L4 memory model is intended to retain successful workflows as reusable Skills/SOPs instead of re-solving every similar task from scratch.
- TMWebdriver is designed to operate a real persistent Chrome/Chromium session, preserving cookies, signed-in state, extensions, and browser-session characteristics.
- It offers terminal and Streamlit interfaces as well as multiple IM entry points, while documenting support for Claude, Gemini, Kimi, MiniMax, and other models.
code_runprovides a documented path for runtime extension through package installation, script creation, and external API calls.
- Its stated scope includes shell execution, file writes, browser control, keyboard/mouse input, and ADB, so adoption requires careful local-permission, account-session, and device-access controls.
- An LLM API key must be configured, but the repository does not provide a unified account-cost model, quota guidance, or detailed configuration for each provider.
- Python 3.14 is explicitly incompatible with
pywebviewand some dependencies, so deployments must stay on Python 3.11 or 3.12. - Web automation requires a manual Chrome-extension installation step, while some advanced functions depend on the agent probing the host, installing dependencies, and saving SOPs.
- The repository links evaluation and browser-detection results to an external technical-report repository; the supplied material does not include the full reproduction configuration.
How does this agent compare with similar options?
The repository compares GenericAgent with OpenClaw and Claude Code. It positions GenericAgent around a smaller core, a minimal atomic toolset, local system control, and accumulated Skills; it characterizes OpenClaw as a multi-service, multi-module system and Claude Code as having a richer CLI toolset with browser control through an MCP plugin. Code-size, capability, and performance assertions in that table are the repository’s own claims and should be tested against the intended deployment and model.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| GenericAgent This agent | 32 · Major gaps | CLIFree + model costs | ★ 14k | 2d ago | Python | Claude API |
| Nuphus Desktop Automation MCP | 72 · Some gaps | MCP serverFree + model costs | ★ 332 | 4d ago | Rust | Claude.ai · OpenAI API · Claude API |
| OpenAdapt | 86 · Good | CLIFreemium | ★ 1.9k | today | Python | — |
| Jev Browser | 75 · Some gaps | MCP serverFree + model costs | ★ 129 | 5d ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: an ask_user tool exists for human confirmation, but its trigger conditions or enforcement are not specified; README claims self-bootstrap but provides no logs or audit evidence; no data flow, sensitive data handling, dependency security, external effects, or rollback mechanisms are documented. Deductions: except for ask_user, other trust criteria lack evidence.
Evidence shows: README and pyproject.toml are largely consistent on Python version and dependencies, but no error handling or failure message documentation is provided; dependency availability is only listed as package names without version pinning or integrity checks. Deductions: failure messages missing, dependency availability evidence thin.
Evidence shows: README describes multiple use scenarios (web automation, OCR, computer use, etc.) and provides cross-platform notes; but capability boundaries are not explicit, trigger precision is only implied via natural language instruction examples, and environment adaptation relies on SOP auto-adjustment. Deductions: capability boundaries and trigger precision evidence insufficient.
Evidence shows: README is well-structured with installation guides, examples, roadmap; MIT license present; but version is only 0.1.0, no CHANGELOG, maintenance responsibility unclear. Deductions: versioning and maintenance responsibility evidence insufficient.
Evidence shows: README claims token efficiency but provides no verifiable benchmark data; marginal value is implied through self-evolution mechanism but lacks independent validation; cost-benefit is based on claims only. Deductions: output usability not specified, cost-benefit evidence thin.
Evidence shows: README references arXiv paper and evaluation benchmarks but provides no specific data or reproduction steps; self-bootstrap claim unverifiable; facts and inferences mixed. Deductions: claim traceability insufficient, cross-source corroboration limited.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- The agent has system-level control (browser, terminal, filesystem, keyboard/mouse, ADB) but no least-privilege or sandboxing mechanisms are provided, posing high risk.
- Self-bootstrap claims and evaluation results in README cannot be verified from the repository; treat with caution.
- Dependencies are not version-pinned and no integrity checks are provided, posing supply chain security risks.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.2.1 GenericAgent v0.2.1 — Windows Desktop
Release notes excerpt
v0.2.1 — Windows / Linux / macOS packages Downloads | Platform | Existing GA installation | GA source + desktop | GA source + desktop + Python | | --- | --- | --- | --- | | Windows x64 | GenericAgent.exe | GenericAgent-Windows-Source.zip | GenericAgent-Windows-WithPython.zip | | Linux x86_64 | GenericAgent-Linux-x86_64.AppImage | GenericAgent-Linux-Source.tar.gz | GenericAgent-Linux-WithPython.tar.gz | | macOS arm64 | GenericAgent-macOS-arm64.app.zip | — | — | …View on GitHub ↗ -
desktop-portable-v0.2.0 GenericAgent Desktop desktop-portable-v0.2.0
Release notes excerpt
GenericAgent Desktop 桌面版 / Desktop 三个平台产物来自同一提交，并在公开发布前统一验证。All three platform artifacts come from one commit and are validated before publication. 安装方法 / Installation - Windows x64：下载 GenericAgent-Desktop-Windows-Portable.zip，解压后双击 GenericAgent.exe。卸载时运行 uninstall.bat，再删除解压目录。 Windows x64: extract GenericAgent-Desktop-Windows-Portable.zip, then launch GenericAgent.exe. Run uninstall.bat before deleting the extracted directory. - Linux x86_64：下载并解压 GenericAgent-Desktop-Linux-Portable.tar.gz，执行 chmod +x GenericAgent.AppImage 后运行它。卸载时运行 uninstall.sh，再删除解压目录。 …View on GitHub ↗ -
desktop-portable-v0.1.4 GenericAgent Desktop desktop-portable-v0.1.4
Release notes excerpt
GenericAgent Desktop 桌面版 / Desktop 无需自行安装 Python、无需联网安装依赖、无需源码；首次启动会自动准备内置运行环境。 No separate Python install, no internet for dependencies, no source checkout required; the bundled runtime is prepared on first launch. 安装方法 / Installation - Windows: 下载 GenericAgent-Desktop-Windows-Portable.zip，解压后双击 GenericAgent.exe 启动。卸载时先退出应用，再双击包内 uninstall.bat，最后删除整个解压目录。 Download GenericAgent-Desktop-Windows-Portable.zip, extract it, then double-click GenericAgent.exe. To uninstall, quit the app, double-click uninstall.bat, then delete the extracted folder. …View on GitHub ↗
FAQ
What credentials are required?
mykey.py from mykey_template_en.py and provide an LLM API key.Is a graphical interface required?
frontends/tui_v3.py terminal UI and the launch.pyw Streamlit UI, and says the [ui] extra can be skipped for headless operation.