Skip to main content

​
Overview

GAIA uses a mise + Nx architecture:
  • mise - Task runner and tool version manager
  • Nx - Build system with caching and project graph
Run mise tasks to see all available commands.

​
Quick Start

mise setup        # First-time setup (deps, docker, seed)
mise dev          # Start API + web (auto-starts Docker)
mise dev:full     # Everything including ARQ worker

​
Development Commands

Run from project root.
CommandDescription
mise devAPI + web in parallel (starts Docker)
mise dev:apiAPI server only (port 8000)
mise dev:webWeb app only (port 3000)
mise dev:mobileMobile app (Expo dev server)
mise dev:desktopDesktop app (Electron)
mise dev:arqARQ background worker
mise dev:voiceVoice agent worker
mise dev:fullAPI + web + ARQ + voice worker
mise dev:docsDocumentation server

​
Setup Commands

CommandDescription
mise setupComplete setup for all apps (env check → deps → docker → seed)
mise setup:envCheck if .env files exist (api, mobile)
mise setup:apiInstall API dependencies (uv sync)
mise setup:webInstall web dependencies (pnpm install)
mise setup:mobileInstall mobile dependencies (pnpm install)
mise setup:desktopInstall desktop dependencies (pnpm install)
mise setup:voice-agentInstall voice agent dependencies + download models
mise setup:depsInstall all dependencies

​
Build Commands

CommandDescription
mise buildBuild all projects
mise build:webBuild web only
mise build:docsBuild documentation
mise build:affectedBuild only changed projects

​
Code Quality

​
Linting

CommandDescription
mise lintLint all projects (parallel with caching)
mise lint:fixLint and auto-fix all projects
mise lint:apiLint API only (ruff)
mise lint:webLint web only (biome)
mise lint:affectedLint only changed projects

​
Formatting

CommandDescription
mise formatFormat all projects
mise format:checkCheck formatting without changes
mise format:apiFormat API only
mise format:webFormat web only
mise format:affectedFormat only changed projects

​
Type Checking

CommandDescription
mise type-checkType-check all projects
mise type-check:affectedType-check only changed projects

​
Testing

CommandDescription
mise testRun all tests
mise test:apiRun API tests (pytest)
mise test:webRun web tests
mise test:affectedTest only changed projects

​
Pre-commit Hooks

GAIA uses prek for pre-commit hooks.
CommandDescription
mise pre-commitRun all checks on all files
mise pre-commit:installInstall git hooks
mise pre-commit:runRun on staged files
mise pre-commit:apiRun checks on API only
mise pre-commit:webRun checks on web only
mise pre-commit:uninstallRemove git hooks

​
Clean & Maintenance

CommandDescription
mise cleanClean all project build artifacts
mise clean:nxReset Nx cache

​
Nx Commands

​
Project Graph

CommandDescription
mise graphOpen Nx project graph in browser
mise affected:graphShow graph of affected projects

​
Direct Nx Usage

# Run any target on a specific project
npx nx <target> <project>

# Examples
npx nx lint api
npx nx build web
npx nx test api

# Run on multiple projects
npx nx run-many -t lint --projects=api,web

# Run on all affected projects
npx nx affected -t lint
npx nx affected -t build
npx nx affected -t test

# Show project config
npx nx show project api
npx nx show project web
npx nx show projects

​
API-Specific Commands

Run from apps/api/ or use mise -C apps/api <task>.

​
Development

CommandDescription
mise devDev server with hot reload
mise startProduction server
mise workerARQ background worker

​
Code Quality

CommandDescription
mise lintRuff linter
mise lint:fixAuto-fix lint issues
mise formatFormat with ruff
mise mypyType checking

​
Security

CommandDescription
mise banditSecurity scanner
mise pip:auditAudit dependencies
mise secretsDetect secrets in code
mise schemaTest API schema

​
Database

CommandDescription
mise seed:modelsSeed AI models
mise seed:workflowsSeed workflows

​
Web-Specific Commands

Run from apps/web/ or use mise -C apps/web <task>.
CommandDescription
mise devDev server with Turbopack (port 3000)
mise buildProduction build
mise startProduction server
mise typeTypeScript type checking
mise lintLint with biome
mise formatFormat with biome
mise analyzeBundle size analysis
mise cleanClean .next and caches

​
Mobile-Specific Commands

Run from apps/mobile/ or use mise -C apps/mobile <task>.
CommandDescription
mise devStart Expo development server
mise androidRun on Android device/emulator
mise iosRun on iOS device/simulator
mise webRun on Web
mise prebuildGenerate native code
mise eas:buildBuild with EAS Build (cloud)
mise eas:submitSubmit to app stores
mise cleanClean build artifacts

​
Desktop-Specific Commands

Run from apps/desktop/ or use mise -C apps/desktop <task>.
CommandDescription
mise devRun desktop app in dev mode
mise buildBuild Electron main and preload
mise startRun built app in production mode
mise distCreate distributable for current platform
mise dist:macCreate macOS distributable (DMG + ZIP)
mise dist:winCreate Windows distributable (NSIS)
mise dist:linuxCreate Linux distributable (AppImage)
mise cleanClean all build artifacts

​
Common Workflows

​
Daily Development

mise dev                      # Start everything
# or
mise dev:api                  # In one terminal
mise dev:web                  # In another terminal

​
Before Committing

mise lint && mise format      # Check code quality
mise type-check               # Verify types
mise test:affected            # Run relevant tests

​
CI/CD Pattern

mise lint:affected            # Only lint changed code
mise type-check:affected      # Only type-check changed code
mise build:affected           # Only build changed projects
mise test:affected            # Only test changed code

​
Tips

​
Run Commands Anywhere

mise -C apps/api dev          # Run API dev from root
mise -C apps/web lint         # Run web lint from root

​
List All Tasks

mise tasks                    # Show all available tasks
mise tasks --hidden           # Include hidden tasks

​
Need Help?

  1. Run mise doctor to check your setup
  2. Ensure Docker is running (docker ps)
  3. Check .env files exist
  4. See Development Setup