Code Agent

Source Code: hub/agents/python/code/gaia_agent_code/agent.py · hub/agents/python/code/gaia_agent_code/tools/

The Code Agent is optimized for full-stack TypeScript web apps (Next.js + Prisma + Tailwind), but Python code generation remains fully supported (and is the default for non-TypeScript requests).

First time here? Complete the Setup guide first to install GAIA and its dependencies.

The GAIA Code Agent turns a natural-language prompt into a working Next.js application. It designs the data model, builds Prisma schemas, generates REST API routes with Zod validation, creates React pages, applies Tailwind styling, validates TypeScript, and iterates until the app builds successfully.

End-to-end generation and auto-debugging for a full-stack app usually takes 10–20 minutes. Timing depends on how much context is created and how many debugging loops are needed. We prioritize output quality while continuously improving speed, and contributions that enhance either are welcome in the GAIA repository.

Key Features

Full-Stack Generation

Next.js apps with API routes, React pages, and Tailwind styling

Prisma Data Modeling

SQLite schemas with autogenerated IDs and timestamps

Validated APIs

REST endpoints with Zod validation and clear error responses

Type-Safe UI

React components for list, create, and detail flows with TypeScript types

Iterative Fixes

TypeScript checks, Next.js builds, and auto-fix loops until green

CLI Control

Step-through, traces, and background process management for long runs

Quick Start

Prerequisite: Install Node.js v20.19.x

Download from nodejs.org (Windows Installer for v20.19.x LTS)
Verify installation: node --version (should show v20.19.x)
Node.js is required to build and run the web application that the GAIA Code Agent generates.

Clone the repository

git clone https://github.com/amd/gaia.git
cd gaia

Install development dependencies

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"

Start Lemonade server (local LLM)

lemonade-server serve --ctx-size 32768

Generate an app

gaia-code "Build me a movie tracking app in nextjs where I can track the movie title, genre, date watched, and a score out of 10" --path movie-web-app

Run the generated app

cd movie-web-app
npm run dev

The app serves at http://localhost:3000

Basic Examples

Workout Tracker
Restaurant Reviews
AI Tool Leaderboard
Simple Todos
Interactive Mode

gaia-code "Build me a workout tracking app in nextjs where I can track workout, duration, date, and goal"

gaia-code "Build me a restaurant rating application in nextjs. I want to be able to put the location of the restaurant, the food that I ate, and my review"

gaia-code "Build me an AI tool rater in nextjs where I can give the name of the AI programming tool, give it a score out of 10 for speed and quality in a text box, as well as provide a description. Show a little leaderboard that will show the highest performing to lowest performing tools by averaging those scores."

gaia-code "Build me a todo tracking app using typescript"

gaia-code --interactive
# then type your prompt when prompted

Next.js Full-Stack App Generation

The Code Agent outputs a complete Next.js project with Prisma, Zod, and Tailwind baked in.

your-app/
├── prisma/
│   └── schema.prisma          # SQLite models with IDs and timestamps
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   └── [resource]/
│   │   │       ├── route.ts        # GET, POST
│   │   │       └── [id]/route.ts   # GET, PUT, DELETE
│   │   ├── [resource]/
│   │   │   ├── page.tsx        # List view
│   │   │   ├── new/page.tsx    # Create form
│   │   │   └── [id]/page.tsx   # Detail view
│   │   ├── layout.tsx          # Root layout
│   │   ├── page.tsx            # Landing page with navigation
│   │   └── globals.css         # Tailwind styles
│   └── lib/
│       └── prisma.ts           # Prisma client bootstrap
├── package.json
├── tsconfig.json
├── tailwind.config.ts
└── next.config.js

Stack defaults:

Next.js with the App Router
TypeScript + strict typing
Prisma ORM with SQLite
REST API routes validated with Zod
Tailwind CSS styling for layouts, forms, and states

Debug and Trace Options

Debug Logging

gaia-code "Create a todo tracking app in nextjs" --debug

See internal decision logs

JSON Trace

gaia-code "Create a todo tracking app in nextjs" --trace

Save detailed execution trace

Full Debug

gaia-code "Create a todo tracking app in nextjs" --debug --trace

Maximum debugging information

JSON Output Structure

The --trace flag saves a complete trace with detailed information:

trace_output.json

{
  "status": "success",
  "result": "Final answer from agent",
  "system_prompt": "Complete system prompt used",
  "conversation": [
    {"role": "user", "content": "User's query"},
    {"role": "assistant", "content": {"thought": "...", "tool": "...", "tool_args": {...}}},
    {"role": "system", "content": {...}}
  ],
  "steps_taken": 28,
  "duration": 123.45,
  "total_input_tokens": 15000,
  "total_output_tokens": 8000,
  "output_file": "/absolute/path/to/output.json"
}

API & VSCode Integration

The Code Agent is available through the GAIA API Server as the gaia-code model, providing an OpenAI-compatible REST API for IDEs and automation.

Quick Start

Start Lemonade server

lemonade-server serve --ctx-size 32768

Install API dependencies

uv pip install -e ".[api]"

Start GAIA API server

uv run gaia api start

Call the model

Linux/macOS
PowerShell

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gaia-code",
    "messages": [{"role": "user", "content": "Build me a movie tracking app in nextjs"}]
  }'

$body = @{
    model = "gaia-code"
    messages = @(
        @{
            role = "user"
            content = "Build me a movie tracking app in nextjs"
        }
    )
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "http://localhost:8080/v1/chat/completions" `
    -Method Post `
    -ContentType "application/json" `
    -Body $body

API Highlights

OpenAI Compatible: Works with OpenAI clients and compatible tooling
Streaming Support: Real-time updates while generating
Multi-Turn: Maintain context across requests

VSCode Integration Guide

API Server Documentation

REST examples and usage

Workflow Capabilities

Analyze Requirements

Interpret the prompt and determine the minimum viable schema

Generate Prisma Schema

Create models with IDs, timestamps, and inferred field types

Build API Routes

Scaffold REST endpoints with Zod validation for CRUD operations

Create React Pages

Generate list, creation, and detail pages wired to the APIs

Apply Styling

Add Tailwind-powered layouts, forms, and state handling

Validate & Build

Run TypeScript checks and Next.js build; collect any errors

Auto-Fix Loop

Apply targeted fixes and re-run validation/build until clean

Available Tools

Project Bootstrap & Processes

run_cli_command - Execute npm/yarn commands and capture output
cleanup_all_processes / stop_process / list_processes - Manage background runs

Data Modeling & APIs

manage_data_model - Create or update Prisma models
manage_api_endpoint - Generate REST routes with Zod validation
validate_crud_structure - Ensure CRUD files exist for each resource

UI & Styling

manage_react_component - Generate list, form, detail React pages
setup_app_styling - Apply Tailwind design system and globals
update_landing_page - Wire navigation and landing content

Validation & Quality

validate_typescript - Run TypeScript compiler checks
test_crud_api - Smoke-test CRUD endpoints
validate_styles - Check CSS and design consistency

Debugging & Error Fixes

fix_code - LLM-driven targeted file fix for validation/build errors (used in remediation checklists)

Tooling Setup

setup_prisma - Initialize Prisma and database config
setup_nextjs_testing - Configure Vitest where needed

External Information Lookup

The agent can optionally use web search (Perplexity) when PERPLEXITY_API_KEY is set in .env to unblock documentation or best-practice questions.

Troubleshooting

LLM server not running

❌ Error: Lemonade server is not running or not accessible.

Start the server with:

lemonade-server serve --ctx-size 32768

TypeScript or build errors keep returning

Ensure dependencies are installed: npm install
Regenerate Prisma client: npx prisma generate
Push schema: npx prisma db push
Re-run the agent with --debug --trace to inspect fixes

Agent gets stuck on a simple bug

Occasionally the agent can loop on a minor issue; try rerunning the command
If it persists, update the prompt to call out the failing component or file

Prisma client issues

Check prisma/schema.prisma for typos
Delete node_modules and reinstall
Verify DATABASE_URL (if using a custom provider)

Port already in use

Stop existing dev servers or run npm run dev -- --port 3001

VS Code Debugging (Developers)

Use the existing launch configurations to step through the agent when it generates Next.js projects.

Available Debug Configurations

Code Agent Debug - Next.js App - Full project generation workflow
Code Agent Debug - REST API - Focus on API route generation
Code Agent Debug - Interactive - Step through with --step-through
Code Agent Debug - With Breakpoint ⭐ - Stops before execution for setting breakpoints

Useful breakpoint locations:

hub/agents/python/code/gaia_agent_code/agent.py - Agent initialization and orchestration
hub/agents/python/code/gaia_agent_code/tools/typescript_tools.py - TypeScript/Next.js tooling
hub/agents/python/code/gaia_agent_code/orchestration/checklist_executor.py - Full-stack checklist workflow
src/gaia/agents/base/agent.py - Base agent loop

Best Practices

Be Specific

Include required fields and relationships in the prompt to shape the Prisma schema

Run Setup Commands

After generation, just cd <path> and run npm run dev (the agent installs dependencies for you)

Review Before Shipping

Inspect API validation, UI flows, and database types before deploying

Iterate with Data

Start with the MVP output, then rerun the agent with refined prompts to add features

Getting Started

C++ Framework

Python Framework

Key Features

Full-Stack Generation

Prisma Data Modeling

Validated APIs

Type-Safe UI

Iterative Fixes

CLI Control

Quick Start

Basic Examples

Next.js Full-Stack App Generation

Debug and Trace Options

Debug Logging

JSON Trace

Full Debug

JSON Output Structure

API & VSCode Integration

Quick Start

API Highlights

VSCode Integration Guide

API Server Documentation

Workflow Capabilities

Available Tools

External Information Lookup

Troubleshooting

VS Code Debugging (Developers)

Best Practices

Be Specific

Run Setup Commands

Review Before Shipping

Iterate with Data

Next Steps

VSCode Integration

API Server

Playbook

Features Overview

​Key Features

Full-Stack Generation

Prisma Data Modeling

Validated APIs

Type-Safe UI

Iterative Fixes

CLI Control

​Quick Start

​Basic Examples

​Next.js Full-Stack App Generation

​Debug and Trace Options

Debug Logging

JSON Trace

Full Debug

​JSON Output Structure

​API & VSCode Integration

​Quick Start

​API Highlights

VSCode Integration Guide

API Server Documentation

​Workflow Capabilities

​Available Tools

​External Information Lookup

​Troubleshooting

​VS Code Debugging (Developers)

​Best Practices

Be Specific

Run Setup Commands

Review Before Shipping

Iterate with Data

​Next Steps

VSCode Integration

API Server

Playbook

Features Overview

Key Features

Quick Start

Basic Examples

Next.js Full-Stack App Generation

Debug and Trace Options

JSON Output Structure

API & VSCode Integration

Quick Start

API Highlights

Workflow Capabilities

Available Tools

External Information Lookup

Troubleshooting

VS Code Debugging (Developers)

Best Practices

Next Steps