| title | Development Guide |
|---|---|
| icon | laptop-code |
Table of Contents
GAIA is an open-source framework that runs generative AI applications on AMD hardware. GAIA runs Large Language Models (LLMs) locally through Lemonade Server.
GAIA utilizes both NPU and iGPU on Ryzen AI systems for optimal performance on 300 series processors or above.
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | Windows 11 Pro 24H2 / Ubuntu 24.04+ | - |
| RAM | 16GB | 64GB |
| CPU | Ryzen AI 300-series | Ryzen AI MAX+ 395 |
| Storage | 20GB free | - |
Driver Requirements:
| Component | Minimum Version |
|---|---|
| Radeon iGPU | 32.0.22029.1019 |
| NPU | 32.0.203.314 |
- Git - For version control
- Lemonade Server - Download from lemonade-server.ai
GAIA uses uv, a fast Python package manager that handles virtual environments, Python installation, and dependencies automatically.
Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iexLinux:
curl -LsSf https://astral.sh/uv/install.sh | shgit clone https://github.com/amd/gaia.git
cd gaiauv venv .venv --python 3.12Note: GAIA supports Python ≥3.10 (classifiers cover 3.10, 3.11, 3.12 in
setup.py), but linting configs (black/mypyinpyproject.toml) are pinned topy312, so 3.12 is recommended for contributors.uvwill download 3.12 automatically if it's not installed.
Windows (PowerShell):
.\.venv\Scripts\Activate.ps1Windows (Command Prompt):
.\.venv\Scripts\activate.batLinux:
source .venv/bin/activateYou should see (.venv) in your terminal prompt when activated.
uv pip install -e ".[dev]"With optional extras:
uv pip install -e ".[dev,talk,rag,ui]"Available extras (see setup.py for the full list):
| Extra | Use case |
|---|---|
dev |
Test + lint tooling (pytest, black, isort, mypy, pylint, …) |
ui |
Agent UI backend (FastAPI + uvicorn + SSE); required for gaia --ui |
api |
OpenAI-compatible API server (gaia api start) |
rag |
RAG document Q&A (FAISS, pypdf, pypdfium2, Office formats; embeddings come from Lemonade) |
talk |
Microphone and speaker I/O for gaia talk (sounddevice); Whisper and Kokoro run in Lemonade |
mcp |
MCP client/server bridge (gaia mcp start) |
image |
Terminal image rendering (term-image) |
eval |
Evaluation framework (ground-truth generation, batch experiments) |
youtube |
gaia youtube --download-transcript |
lint |
Standalone lint dependency bundle |
GAIA ships a .claude/settings.json that declares two recommended Claude Code plugins from the official Anthropic marketplace:
frontend-design— higher-quality, less generic UI generationsuperpowers— structured dev methodology (brainstorm → plan → TDD → review)
Plugins are not auto-installed silently. The first time you open this repo in Claude Code (v2.1.0+), you'll see a prompt:
"This project declares plugins. Install them?"
Accept it once and the plugins become available for the repo. You can verify with:
claude --version # must be >= 2.1.0
claude plugin list # shell command — lists installed plugins + status
# or, inside a Claude Code session, type `/plugin` to open the interactive plugin menuTo opt out, copy the entry into your local .claude/settings.local.json with false:
{
"enabledPlugins": {
"superpowers@claude-plugins-official": false
}
}When done working:
deactivateSee also: Agent SDK Documentation
gaia -v # Check version
gaia -h # View CLI optionsgaia chatNote: GAIA starts Lemonade Server when needed —
gaia daemonsupervises it, so there is nothing to launch first. To bring it up ahead of time, or to check on it, usegaia daemon startandgaia daemon status.
Start the Agent UI (backend + frontend) with the convenience scripts:
Linux / macOS:
./installer/scripts/start-agent-ui.sh # Start both backend + frontend
./installer/scripts/start-agent-ui.sh --backend-only # Backend only (port 4200)
./installer/scripts/start-agent-ui.sh --frontend-only # Frontend dev server only (port 5174)Windows PowerShell:
.\installer\scripts\start-agent-ui.ps1 # Start both backend + frontend
.\installer\scripts\start-agent-ui.ps1 -BackendOnly # Backend only (port 4200)
.\installer\scripts\start-agent-ui.ps1 -FrontendOnly # Frontend dev server only (port 5174)Or start manually:
# Terminal 1: Backend
uv run python -m gaia.ui.server --debug
# Terminal 2: Frontend (Vite dev server with hot reload)
cd src/gaia/apps/webui && npm run devDev QA mode. To run the built desktop app against this checkout's backend
without touching an installed GAIA, set GAIA_BIN to a gaia executable in an
unpackaged build. The app then skips the installer and the pidfile, and writes the browser pane's discovery file under its
own user data dir instead of ~/.gaia/run/. The QA kit does this for you with a
throwaway user data dir, and serves the browser pane fixture site:
uv venv ../gaia-qa-venv && uv pip install --python ../gaia-qa-venv/bin/python \
-e ".[dev,ui]" -e hub/agents/chat/python -e hub/agents/gaia/python
cd src/gaia/apps/webui && npm run build && cd -
GAIA_BIN=../gaia-qa-venv/bin/gaia node src/gaia/apps/webui/scripts/qa-pane.mjs launch
node src/gaia/apps/webui/scripts/qa-pane.mjs chat "What is the title of the page open in the browser pane?"Run qa-pane.mjs with no command for the rest (state, open, shot, quit, ...).
The backend still reads and writes the usual ~/.gaia (chat history, logs).
Changed a backend pydantic model? Regenerate the frontend's API types, or CI fails:
python -m gaia.ui.export_openapi # writes src/types/api.schemas.json
cd src/gaia/apps/webui && npm run gen:api-types # writes src/types/api.gen.ts
npx tsc --noEmit # checks the hand-written types still matchIf tsc then flags src/types/apiContract.ts, update the matching interface in src/types/index.ts.
util/lint.py drives all repo lint tooling. Running it with no flags runs
every check in sequence; pass a specific flag to run one:
python util/lint.py --all --fix # Run everything; autoformat with black + isort
python util/lint.py --black # Code formatting
python util/lint.py --isort # Import sorting
python util/lint.py --pylint # pylint
python util/lint.py --flake8 # flake8
python util/lint.py --mypy # type checking (blocking only on already-clean modules)
python util/lint.py --bandit # security scan
python util/lint.py --imports # custom import-cycle check
python util/lint.py --workflow-triggers # reject on.pull_request.branches filters
python util/lint.py --workflow-ancestor-skip # reject job if: conditions an upstream skip silently skips
python util/lint.py --test-lanes # reject test files that no CI lane runs
python util/lint.py --ci-paths # reject CI lanes whose paths: filter misses a file they depend on
python util/lint.py --tool-descriptions # hold tool docstrings to the schema budget
python util/lint.py --doc-versions # verify versions in docs match src/gaia/version.py
python util/lint.py --release-versions # every version field matches its sourceBeing named isn't the same as running. A file with a module-level
pytest.importorskip (for a hub wheel like gaia_agent, or an optional
extra) skips wholesale in any lane that lacks the package. The unit lane and the
lanes that install hub wheels run util/check_module_skips.py right after their
install step. It fails on such a skip unless the file is listed
under module_skips: in the same allowlist, with runs_in naming the lane that
installs the package. That lane must name the file and run the check too.
The TUI workflow (build_tui.yml) narrows the same way: a pull request whose
only files in its paths filter are under src/gaia/apps/webui/ runs one job,
"Freeze core with the UI", instead of the Go tests, six-target build and
installers. TUI Build & Test Result is its one check. The ci:full label is
read when the run starts, so add it and then push.
git diff --name-only origin/main... | python util/check_ci_path_coverage.py --changed -python -m pytest tests/unit/ # Unit tests only
python -m pytest tests/ -xvs # All tests, verbose
python -m pytest tests/ --hybrid # Cloud + local testingKey fixtures live in tests/conftest.py (api_client, api_server,
require_lemonade, lemonade_available). The require_lemonade fixture
auto-skips integration tests when no Lemonade server is running.
Publishing to the hub is irreversible — hub.amd-gaia.ai has no unpublish
route, so a bad release is permanent and public. Before running any
release_*.yml workflow that publishes, prove the pipeline locally:
python util/verify_publish_pipeline.pyIt boots workers/agent-hub under wrangler dev with Miniflare's simulated R2,
drives the real publishers against it, and asserts on behaviour — the happy path,
idempotent re-runs, immutability, the oversized direct-to-R2 lane, and the
pre-flight checks that must refuse to publish anything at all. It refuses to run
against any non-loopback URL, needs no credentials, and cleans up after itself.
It skips with a message (not a failure) when Node.js is unavailable.
*There are two publisher scripts and they are different programs.
hub/agents/gaia/python/packaging/publish_to_r2.py backs release_agent_gaia.yml;
hub/components/terminal-hub/publish_to_r2.py backs the components release (the
TUI). Proving one says nothing about the other, so the harness runs both by default
and labels every row with the publisher it came from. Use --publisher gaia or
--publisher terminal-hub to narrow it. A case that needs a capability a
publisher does not have is reported N/A, never passed.
Read the module docstring for what it deliberately cannot prove — real R2 credentials from GitHub's IP space, real installer sizes, and the macOS freeze legs still only get exercised in CI.
The harness runs on bogus credentials against a local Worker, so it proves
the publish logic and nothing about whether the real key works. Every artifact
over the Worker's request-body cap — today the flagship agent's sidecar
builds — is PUT straight to R2 instead, and R2 answers both a bad
credential and a malformed request with the same Unauthorized:
python util/check_r2_credentials.py --size-mb 120It checks bucket scope, a checksummed write, a write at real release size, and a round-trip back through the hub Worker, naming the first that fails. That last check is the one worth understanding: a credential can happily write to a same-named bucket in a different Cloudflare account, and only the Worker serving the bytes back rules that out.
It reads .env (gitignored) or the environment, writes probes under
agents/_credential-probe/ and deletes them, and prints no secret value. It
still cannot prove the credential works from GitHub's runners — a token with
Client IP Address Filtering passes locally and fails in CI.
src/gaia/version.py is the only version you edit for a core release. One
command writes every field that follows it, and lint fails when one drifts,
naming the file, the value it found, and the value it expected:
python util/release_versions.py --stamp # write every field from its source
python util/release_versions.py --check # what lint runs; changes nothing| Source | Fields that follow it |
|---|---|
src/gaia/version.py |
Agent UI package.json and lockfile; version in hub/components/terminal-hub/gaia-agent.yaml; the docs/docs.json navbar label (with LEMONADE_VERSION); the flagship agent's amd-gaia>= floor and min_gaia_version, and the minimum core in the flagship's npm README.md and SKILL.md |
hub/agents/gaia/python/gaia_agent/__init__.py |
The flagship's pyproject.toml, gaia-agent.yaml, npm/package.json, and npm/binaries.lock.json version and sidecar URL |
--stamp does the work of installer/version/bump-ui-version.mjs, the flagship's
stamp_version.py, and the hand edits to the Terminal UI manifest and the navbar.
Those scripts still work, and release workflows still call them.
--stamp vX.Y.Z-rcN writes a release candidate's versions into the same files
as util/release_tag.py stamp, with the same result.
The flagship agent keeps its own version until it joins core's (#5172).
gaia init, the one-line installers (install.sh / install.ps1) and the
Windows setup install the flagship agent's gaia-agent binary from the download server (hub.amd-gaia.ai) and from the pin in
hub/agents/gaia/npm/binaries.lock.json. Only release_agent_gaia.yml (tag
agent-pkg-gaia-vX.Y.Z) fills either, so a core release does not rebuild it.
A final core release therefore fails unless that flagship release was cut from
the same code: same frozen sources at its tag, its hashes committed to the
lock, and it is the hub's latest. The flagship release opens a PR that commits
those hashes to the lock once it publishes; merge it, then check before tagging:
git fetch --tags origin
python util/check_flagship_release.pyA release can go out as a candidate first, so testers get the exact build before
it becomes what pip install amd-gaia and the website hand everyone. Tag
vX.Y.Z-rcN on a commit whose src/gaia/version.py already says X.Y.Z (the
release PR has landed); publish.yml runs the usual pipeline, behind the same
approval, and keeps the result off every stable channel:
- GitHub — a pre-release, never marked latest, with the one-step Windows
setup (
gaia-X.Y.Z-rc.N-win-x64-setup.exe), the desktop app installers, the terminal binaries, and the wheel attached. If the Windows setup fails to build or fails its smoke test, the pre-release still ships without it, its notes say so, and the run fails. - GAIA agent — the flagship
gaia-agentbinaries, frozen from the candidate's commit and attached to the pre-release withgaia-agent-release.json. The candidate'sgaia initand Windows setup use these, never the download server'sgaia, which can be many commits older. A candidate whose flagship build fails is not published; an install that cannot reach the pre-release's agent fails with the reason.GAIA_RC_FLAGSHIP_URLpoints a candidate core at another copy of those assets (afile://directory works); the release pipeline uses it so the frozen core's real-engine check installs the flagship from the same run, before the pre-release exists. - PyPI —
X.Y.ZrcN.pip install amd-gaiaskips it;pip install --pre amd-gaiaoramd-gaia==X.Y.ZrcNgets it. - npm —
@amd-gaia/agent-ui@X.Y.Z-rc.Nunder thenextdist-tag;latestdoes not move. - Website — a collapsed "Try the release candidate" entry under the stable downloads, shown only while the candidate is newer than the latest release.
- Not published — Download-server components (the catalog has no pre-release
channel) and the terminal's
.pkg/.deb/.rpmpackages, which need a numeric-only version.
Tests never hold a candidate: it publishes as soon as its own builds and the
smoke tests of those artifacts pass. CI on its commit (lint, the unit tests on
every OS, the integration lanes, the release dry run) is read once and shown on
the run as passed, failed, still running, or not run, with a warning for each
that isn't green. A final requires all of it except the Linux NPU agent-chat
check, waits for it, and needs a passing dry run on its commit, so clear an RC's
warnings before tagging the final. The Linux NPU check still runs and shows as a
warning on the final, but doesn't hold it until its runners can lock enough
memory for the NPU model (#6764).
RC_REPORTED, FINAL_REQUIRED and FINAL_ADVISORY in
util/check_release_ci.py are the lists.
The candidate reuses the final's release notes (docs/releases/vX.Y.Z.mdx), and
the -rcN suffix is stamped from the tag at build time, so the final vX.Y.Z
can be tagged on the same commit once testing passes. Check a tag before pushing
it:
python util/release_tag.py classify v0.25.0-rc1The full sequence (RC, test pass, -rc2 if needed, final) is the RC phase of the
gaia-release skill in .claude/skills/gaia-release/SKILL.md.
Unit and integration tests prove code paths; they don't prove a feature works
end-to-end on real hardware. GAIA ships a gaia-testing skill (under
.claude/skills/) for Claude Code: it drives
the real interface — the Agent UI in a browser, the CLI, or the Agent UI MCP
server (gaia mcp serve) — and brings back screenshots, logs, traces, and
per-operation timing as evidence, all collected to your local machine. In a
session, ask it to "test / validate / QA this feature with screenshots"; it
scales from a unit-only run up to a full real-world run gated by a single
approval prompt.
The real-world tier runs on a machine you nominate. The skill discovers
candidates from your loaded Claude config only — it never scans your
filesystem. Declare machines under a ## Dev Machines (or ## Test Machines)
heading in either:
- your user-level
~/.claude/CLAUDE.md(shared across all your projects) — which may summarise them inline and point to a detail file it loads, such as~/.claude/memory/dev-machines.md; or - the project
./CLAUDE.mdor.claude/settings.json.
Record each machine's name, access method (local, SSH host, or container), hardware class (CPU / discrete GPU / Ryzen AI NPU), and any setup or test commands. With nothing declared, the skill targets your local machine.
## Dev Machines
- my-gpu-box — SSH host, Ubuntu 24.04, discrete Radeon GPU; good for dGPU inference tests.
- my-npu-laptop — local, Ryzen AI NPU; good for NPU device-path tests.Keep credentials out of committed files. Put sudo passwords, tokens, and keys only in your user-level config (or a memory file it points to) — never in the repo's
CLAUDE.mdor.claude/settings.json. The skill reads them write-only and never echoes them into logs, screenshots, or reports.
A slow local turn is almost always prefill: the system prompt and tool schemas are re-sent on every LLM call, so prompt size converts directly into seconds. None of that is visible in the default stats line, which shows only elapsed time.
Set GAIA_TURN_LOG to a file path to turn on per-turn recording:
export GAIA_TURN_LOG=~/.gaia/turns.jsonl
gaia --devEach turn appends one JSON object (schema gaia.turn/1) with the fixed prefill
size, cached-vs-new input tokens per call, output tokens, the wall-time split
across model / tools / agent overhead, and absolute timestamps — so a session
is greppable and two builds are diffable.
With --dev, the TUI also draws the same breakdown under each answer:
34.5s · ttft 2.1s · 14.2 tok/s · 3 steps · 17.0k prefill
turn a3f1c2 22:47:35Z → 22:48:09Z 34.5s total
model 28.4s · tools 4.8s · overhead 1.3s
in 51,204 tok (38,110 cached, 13,094 new · 74% hit) · out 210 tok
prefill 17.0k fixed · 66 tools · skills: gaia-voice
Unset, recording is off and costs nothing — the recorder is never constructed and the agent's wire payload is unchanged.
Token counts marked *cached* / *new* come from a client-side estimator (`tiktoken` when installed), not from the model's own tokenizer. Read them as ratios and deltas — how much a prompt shrank, what share was cache-eligible — not as exact model token counts. `out` is the backend's own count.On a local llama.cpp model, each call in the record also carries the server's
own accounting for that request, read from the stream's timings, so it never
mixes in another client's request:
| Field | Meaning |
|---|---|
llm_calls[].server |
prompt_n tokens prefilled, cache_n tokens reused from the KV cache, prompt_ms / predicted_ms, and compute_s (their sum) |
llm_calls[].client |
Time spent before the request reached the server: lease_wait_s (daemon model-slot lease), lock_wait_s (this process's per-model request lock), ensure_loaded_s (the model status probe), stats_fetch_s |
totals.server_compute_s |
Seconds the server computed for this turn |
totals.non_model_s |
Turn wall time minus server compute: what GAIA, its tools, and the user cost |
spans |
Named stretches of agent work, such as memory_context, skill_recall, memory_post_init, context_evict, memory_tool_log, parse_response |
gaps |
The time between consecutive model calls, with the tools and spans that filled it |
server_compute_s and non_model_s appear only when every call reported
timings; a partial sum would understate the model and overstate GAIA. Work that
runs after the answer (memory writes) is appended as a second line with schema
gaia.turn_post/1 and the same turn_id.
The flagship sidecar also serves the last records at
GET /v1/gaia/debug/turns?limit=N (with its caller token) while GAIA_TURN_LOG
is set. The route is off the versioned contract and returns 404 otherwise. It
returns every session's records, queries included, to anyone holding the
caller token, so keep turn recording on only on a machine you use alone.
To watch the server itself, util/perf_turns.py drives /v1/gaia/query and
samples the llama.cpp server behind Lemonade: /slots for per-slot busy time
and idle gaps, /metrics for prefill and decode seconds, and, on Windows, GPU
utilization per process. It waits for an idle GPU before each session and flags
a run during which the model was reloaded or another client sent requests. It
approves every tool confirmation by itself, so only give it queries whose tools
you would approve:
python util/perf_turns.py --sidecar http://127.0.0.1:4311 --token TOKEN --query "hello" --runs 3 --out runs.jsonlA --trace run writes agent_output_<timestamp>.json, and its tool_schema
block records what went out to the backend as tools= on that run — the tool
names, the per-turn filter (null when the full registry was sent), the
serialized schema size in chars and tokens, and the schema text itself. With
the file's system_prompt and conversation alongside it, a prompt can be
split into system / tools / history shares from one artifact, and a tool that
never reached the model is visible by its absence from tool_names.
The schema text is the bulky part. Set GAIA_TRACE_TOOL_SCHEMA=0 to drop just
that text — the names and sizes stay, and the artifact records a
schemas_omitted note so a smaller trace never looks like a full one.
After installing uv, the command may not be recognized because PATH hasn't updated.
Solution 1: Restart PowerShell (simplest)
Solution 2: Update PATH in current session:
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"Solution 3: Use full path:
$env:USERPROFILE\.local\bin\uv.exe --versionIf you see a script execution error:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser- Check available system memory
- Verify model compatibility with your hardware
- Ensure all dependencies are correctly installed
- Verify the virtual environment is activated (look for
(.venv)prefix) - Try restarting your terminal
- Re-run the activation command for your platform
Report issues to gaia@amd.com or create an issue on GitHub.
License
Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
SPDX-License-Identifier: MIT