Installation Guide

May 16, 2026 · View on GitHub

This is the detailed installation guide for GenericAgent.

Two audiences:

  • For Humans — you are installing GA for yourself.
  • For LLM Agents — you are a coding agent such as Claude Code, or Codex installing GA for a human user. Read that section first so you do not guess.

The shortest install commands live in the main README. This guide adds platform notes, key setup, verification, troubleshooting, and agent-safe rules.

For Humans

Prerequisites

RequirementNotes
OSWindows 10/11, macOS 12+, or a modern Linux distribution.
PythonUse Python 3.11 or 3.12. Do not use Python 3.14 — it is incompatible with pywebview and a few GA dependencies. The one-line installer ships an isolated Python environment, so manual Python setup is usually unnecessary.
GitRecommended for updates and self-evolution.
LLM API keyGA speaks two native protocols: OpenAI-compatible APIs and Anthropic Claude native APIs. GPT-family models, Claude, Kimi, MiniMax, DeepSeek, GLM, Qwen, Gemini through OAI-compatible gateways, and similar providers can be configured through mykey.py.

This is the easiest path. It prepares an isolated runtime, downloads GenericAgent, installs the core dependencies, and gives you a ready-to-run local project tree.

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

After installation, launch the desktop app from:

frontends/GenericAgent.exe

Or run from the project directory:

python launch.pyw

GenericAgent is meant to grow its environment through the Agent itself, not by pre-installing every possible package. Start small, then let GA install task-specific tools when it actually needs them.

Custom install location

INSTALL_DIR="$HOME/work/GenericAgent" GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

$env:INSTALL_DIR="C:\dev\GenericAgent"; powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Force reinstall

Use this only when you know you want to refresh the installed files. Back up mykey.py, memory/, skills/, and any local work first.

FORCE=1 GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

Method 2: Python install (for developers)

Use this when you want a normal editable checkout.

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]"        # Core + UI dependencies
cp mykey_template.py mykey.py     # Fill in your LLM API key
python launch.pyw

Full guide: GETTING_STARTED.md

Configure your LLM key

  1. Open the installed GenericAgent directory.
  2. If mykey.py does not exist, copy it from mykey_template.py.
  3. Fill in one provider. Do not paste example keys as real keys.
  4. If you are unsure about the fields, read the comments in mykey_template.py first.

GA supports:

  • OpenAI-compatible endpoints — Chat Completions / Responses shaped APIs.
  • Anthropic Claude native — Claude Messages API.

Optional helper:

python assets/configure_mykey.py

Frontends

Desktop App

For one-line installs on Windows, double-click:

frontends/GenericAgent.exe

Terminal UI

A lightweight keyboard-driven interface built on Textual. It supports multiple concurrent sessions and real-time streaming.

python frontends/tuiapp_v2.py

Streamlit UI

python launch.pyw

Verify the install

From the GenericAgent directory:

python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

Then launch at least one frontend:

python launch.pyw
# or
python frontends/tuiapp_v2.py

Common gotchas

Python 3.14 is not supported

If your system python --version reports 3.14, do not use it for GA. Use the one-line installer, or create a Python 3.11 / 3.12 environment with uv.

ga command conflict

Some systems already use ga for another tool. Check first:

type ga

If it resolves to something unexpected, do not rely on the shortcut. Run GA from the install directory with python launch.pyw or python frontends/tuiapp_v2.py.

Windows TUI rendering issues

TUI rendering on Windows depends on terminal, font, and textual version.

  1. Upgrade Textual first: pip install -U textual.
  2. Prefer Git Bash on Windows over classic PowerShell / cmd when Unicode or key bindings look broken.
  3. If it still looks wrong, ask GA itself to repair the terminal compatibility. Example prompt:

    "My experience using frontends/tuiapp_v2.py in PowerShell / cmd / Git Bash on Windows is very poor — lots of incompatibility. Please refer to Claude Code's best practices for the Windows terminal and fix all font and rendering incompatibilities."

pywebview install fails on Linux

Desktop mode depends on GTK / WebKit packages. On Debian / Ubuntu:

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev
pip install pywebview

On headless servers, prefer the TUI or run Streamlit in browser mode instead of desktop mode.

Update an existing install

Do not delete a working GA directory just to update it. It may contain the user's mykey.py, memory, skills, and local work.

cd ~/GenericAgent
git fetch
git pull
uv pip install -e ".[ui]"

If git pull reports conflicts:

  • For mykey.py, memory/, skills/, temp/, and user-created artifacts: prefer the local copy.
  • For core code such as agent*.py, frontends/*, reflect/*, and tools/*: usually prefer upstream unless the user says otherwise.
  • Resolve explicitly, then git add and commit the merge.

For LLM Agents

IMPORTANT: fetch this file with curl, not a summarized web reader. Summaries often drop flags, command quoting, and safety rules.

curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md

You are installing GenericAgent for a human user. Be direct, verify each step, and avoid destructive cleanup unless the user explicitly authorizes it.

Step 0: Inspect before acting

Check:

  1. OS: uname -a, $env:OS, or python -c "import platform; print(platform.system())".
  2. Existing install: ~/GenericAgent/launch.pyw, %USERPROFILE%\GenericAgent\launch.pyw, or a .git directory.
  3. Python version: must be 3.11 or 3.12 if you use the developer path.
  4. Git availability: git --version.
  5. API key readiness: ask the user if no key is available. Never invent one.

Step 1: Choose the install path

Default to the one-line installer unless the user already has a checkout.

Windows PowerShell

powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm http://fudankw.cn:9000/files/ga_install.ps1 | iex"

Linux / macOS

GLOBAL=1 bash -c "$(curl -fsSL http://fudankw.cn:9000/files/ga_install.sh)"

If the user explicitly wants a developer checkout:

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

Step 2: Configure keys safely

  • Read mykey_template.py before editing mykey.py.
  • Configure only keys the user actually provides.
  • Never print the full key back to the user.
  • If the user is unsure, run python assets/configure_mykey.py or ask which provider they want to use.

Suggested question:

Which LLM should GenericAgent use? GA supports OpenAI-compatible endpoints and Anthropic Claude native APIs. Which provider do you want to configure, and do you already have an API key?

Step 3: Verify setup

Run:

cd ~/GenericAgent
python -c "import agent_loop; print('OK')"
git rev-parse --short HEAD

Then verify one frontend:

python launch.pyw
# or, for terminal-only environments:
python frontends/tuiapp_v2.py

Step 4: Verification and Next Steps

Read this document again and think through whether you have done everything correctly:

  • You inspected the OS, existing install, Python version, Git, and key readiness before acting.
  • You used the correct GA install command for this English guide, including GLOBAL=1 where shown.
  • You configured only real user-provided keys and did not reveal secrets.
  • You verified import, Git commit hash, and at least one frontend.

Say 'Congratulations! 🎉' to the user

Say to user: Congratulations! 🎉 You have successfully set up GenericAgent! Double-click frontends/GenericAgent.exe on Windows, or run python frontends/tuiapp_v2.py in your terminal to start using it.

Report the concrete result

Tell the user:

  1. Install path.
  2. Git commit hash.
  3. Which frontend you verified.
  4. Whether mykey.py is configured, without revealing secrets.
  5. Recommended next reading: Hello GenericAgent and GETTING_STARTED.md.

Ask for a Star ⭐

After everything is set up and working, you may ask:

If you found this helpful, would you like to star the GenericAgent repository? It helps the project grow! ⭐

Only open or run anything related to starring the repository if the user explicitly agrees.

Never do these

  • Do not run pip install genericagent; GA is not a PyPI package.
  • Do not delete ~/GenericAgent or %USERPROFILE%\GenericAgent for a "clean install" without explicit user approval.
  • Do not fabricate API keys or treat sample keys as real.
  • Do not assume ga is a valid shell command; check first.
  • Do not rely on ga update; use git fetch, git pull, and reinstall dependencies as shown above.

References