Skip to content
Get packs

Guide · Open source

How to use GenericAgent: install, configure and run it

Updated · written with AI from the project's own documentation and checked against our catalogue data

GenericAgent is an open-source Python framework that lets a large language model operate a local computer through a small set of tools: a browser, terminal, filesystem, keyboard and mouse, and screen reading. This guide shows you how to install it from the README, add your own LLM API key, launch one of its interfaces and understand where it fits. It is aimed at developers and tinkerers comfortable running Python, not at people looking for a one-click app.

GenericAgentlsdefine/GenericAgent · ★ 14.4k · MIT

Quick start

  1. 1Check Python and tools. Confirm you have Python 3.11 or 3.12, Git and uv. Do not use Python 3.14.
  2. 2Clone the repository. Run the git clone command and change into the GenericAgent folder.
  3. 3Create the environment and install. Run uv venv, then uv pip install -e ".[ui]".
  4. 4Add your API key. Copy mykey_template_en.py to mykey.py and fill in your LLM API key.
  5. 5Launch the UI. Start python frontends/tui_v3.py for the terminal UI, or python launch.pyw for Streamlit.

Check the prerequisites before you install

GenericAgent needs Python 3.11 or 3.12. The README says not to use Python 3.14, because it is incompatible with pywebview and some other dependencies. You also need Git, uv (the install command in the README uses it), and an API key from an LLM provider.

  • Python 3.11 or 3.12 (not 3.14)
  • Git
  • uv
  • An LLM API key

Clone the repository and install the dependencies

Clone the repo, enter the folder, then create a virtual environment and install the package with the UI extras. The README recommends this method.

The core agent needs only requests plus a few small packages for the local TMWebdriver server. The [ui] extra adds frontend libraries such as Streamlit and prompt_toolkit/rich. You can skip it and run the agent headless.

git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent uv venv && uv pip install -e ".[ui]"

Add your LLM API key

Copy the config template and open the new file to fill in your LLM API key. The README tells you to edit the copied file, mykey.py, rather than the template.

  • Run the copy command shown below.
  • Open mykey.py and add your API key for the model you want to use.
cp mykey_template_en.py mykey.py

Launch an interface

The README lists a terminal UI as the recommended option, and a Streamlit web UI as an alternative. Run whichever you prefer from inside the GenericAgent folder.

For bot access, the README also lists Telegram, Discord and Lark/Feishu frontends, each started with its own script.

  • Terminal UI (recommended): python frontends/tui_v3.py
  • Streamlit web UI: python launch.pyw
  • Telegram: python frontends/tgapp.py
  • Discord: python frontends/dcapp.py
  • Lark / Feishu: python frontends/fsapp.py
python frontends/tui_v3.py

Understand how it learns skills

GenericAgent is built around nine atomic tools and an Agent Loop of about 100 lines. Each time it solves a new task, it saves the execution path as a reusable Skill. Over time these skills form a skill tree that the agent can draw on.

The README says the agent starts from a seed of about 3K lines and does not preload skills. Your skill library therefore reflects the tasks you have actually run.

  • Nine atomic tools cover browser, terminal, filesystem, keyboard/mouse, and screen vision.
  • Solved tasks are stored as Skills.
  • Skills accumulate with use rather than being preinstalled.

Troubleshoot the terminal UI on Windows

The README says TUI rendering on Windows can be unreliable depending on the terminal and font. It recommends Git Bash over PowerShell or cmd, and suggests upgrading prompt_toolkit and rich first.

  • Upgrade the libraries: pip install -U prompt_toolkit rich
  • Prefer Git Bash on Windows.
pip install -U prompt_toolkit rich

What people use it for

  • Automating repetitive steps in a web browser, such as filling forms or checking pages.
  • Running terminal and filesystem tasks on your own machine through natural-language instructions.
  • Reusing a workflow the agent learned earlier, since solved tasks are stored as Skills.
  • Studying or modifying a small agent codebase, since the core is described as about 3K lines.
  • Sending batch messages or driving a phone app through ADB, as the README's demos show.

Frequently asked questions

Is GenericAgent free?

GenericAgent is released under the MIT licence, as stated in the project listing. You still need your own LLM API key, and the README does not list costs for the model provider you choose.

What do I need to run GenericAgent?

You need Python 3.11 or 3.12, Git, uv and an LLM API key. The README warns against Python 3.14 because some dependencies are incompatible with it.

How do I install GenericAgent?

Clone the GitHub repository, run uv venv and uv pip install -e ".[ui]", then copy mykey_template_en.py to mykey.py and add your API key. The README also offers a one-line installer script for Windows and Linux/macOS.

Why does GenericAgent fail to start on Python 3.14?

The README says Python 3.14 is incompatible with pywebview and a few other GenericAgent dependencies. Install Python 3.11 or 3.12 and create the virtual environment with that version.

Is GenericAgent safe to run on my computer?

The project gives the agent broad system control, including terminal, filesystem, and keyboard and mouse input. Treat it as powerful software: review what it does and avoid giving it access you would not give a script you have not read.

How does GenericAgent compare to Open Interpreter, AutoGPT, OpenHands or Browser Use?

The listing names these as comparable projects. GenericAgent's distinguishing features in its README are the small codebase and the skill-accumulation design. Compare them on the features you need, since this guide does not benchmark them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

GenericAgent suits developers who want a small, readable Python agent they can modify, and who are comfortable installing from source and supplying their own API key. It is not a good pick for non-technical users wanting a polished app, or for anyone who needs strong guarantees about what an agent does on their machine.

Install options & downloads