The API (apps/api)
db/repositories/. apps/api/CLAUDE.md is the full contract.
The web app (apps/web)
(main), are Next.js route groups: they share a layout without adding to the URL. API request and response types are generated from the API’s OpenAPI schema into @gaia/shared/api/generated, never written by hand. apps/web/CLAUDE.md covers state, components and styling.
Shared libraries
The Python apps get
gaia-shared through the uv workspace, so uv sync installs it. Shared code goes here rather than being copied between apps.
Packages
packages/cli is the gaia command, published to npm as @heygaia/cli. CLI internals covers trying and releasing it. packages/gaia-ui holds only a README: the @heygaia/ui component kit lives in its own repository.
How Nx runs everything
Every app, library and package is an Nx project with aproject.json that declares its targets: dev, build, lint, type-check, test and so on. The root mise tasks call Nx, and Nx runs the targets in dependency order, in parallel, and caches the result so unchanged projects are skipped.
api, web, mobile, desktop, voice-agent, cli, docs, wake-word), with a few exceptions: the bots are bot-discord, bot-slack, bot-telegram, bot-whatsapp and bot-imessage, the bot simulator is bot-harness, the shared bot tests are bots-e2e, the shared libraries are shared-python and shared-typescript, and the Docker services are docker.
mise can also run a task defined in an app’s own mise.toml from the root, with // syntax: mise //apps/api:mypy runs mypy from apps/api/mise.toml. Commands lists them.
Next
Conventions
How GAIA code is written: style, commits, design.

