Source Code: src/gaia/api/ | src/vscode/gaia/

GAIA VSCode Integration

Overview

GAIA can be integrated with Visual Studio Code in two powerful ways:

VSCode Extension

Use GAIA agents as selectable language models in VSCode’s model picker

MCP Integration

Connect directly using the Model Context Protocol

VSCode Extension (API Server)

Overview

The GAIA VSCode extension integrates GAIA agents as selectable language models in Visual Studio Code, allowing you to use GAIA’s autonomous agents alongside GitHub Copilot and other language model providers.

Features

GAIA Code Agent: Autonomous Python development with planning, code generation, linting, and testing
GAIA Jira Agent: Natural language interface for Jira operations
Seamless Integration: Works with VSCode’s built-in model picker and Copilot Chat
Local Processing: All inference runs locally on your AMD hardware via GAIA

Prerequisites

Install GAIA Framework

Install GAIA with API support. See API Server Prerequisites

Start Lemonade Server

Ensure the LLM backend is running with extended context:

lemonade-server serve --ctx-size 32768

Install Node.js v20.19.x

Required for building the VSCode extension

Windows
Linux

Download and install from nodejs.org (select Windows Installer for v20.x LTS)Verify installation:

node --version

Should show v20.x.x

Install using nvm (recommended):

# Using nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20

Or using NodeSource repository (Debian/Ubuntu):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify installation:

node --version

Install GitHub Copilot Chat

Install from the VSCode Marketplace

This provides the chat UI that GAIA models integrate with via the Language Model Provider API

Getting Started

GAIA Code requires three services running simultaneously:

Lemonade Server (LLM backend on port 8000)
GAIA API Server (REST API on port 8080)
VSCode Extension (installed in VSCode)

Follow these steps in order:

Start Lemonade Server (LLM Backend)

lemonade-server serve --ctx-size 32768

Keep this terminal running and open a new terminal for the next step

Start the GAIA API Server

gaia api start

The server will run on http://localhost:8080 by default. Keep this terminal running.

Build and Install the Extension

Option A: Build and Install from VSIX
Option B: Development Mode

First, build the extension:

cd src/vscode/gaia
npm install
npm run package

This creates gaia-vscode-0.1.0.vsix in the extension directory.Then install it:

code --install-extension gaia-vscode-0.1.0.vsix

Next Steps

Open a new instance of VSCode
Open a directory (e.g., ~/src/test) that you wish to test GAIA Code against in the new VSCode instance

Select a GAIA Model

Open the VSCode Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Select “Chat: Manage Language Models…” or follow this guide
Click on the model picker
Select a GAIA model using Github Copilot Chat from the Secondary Side Bar

GAIA API server must be running to see available models

Use GAIA in Chat

Type your request in the GitHub Copilot chat and GAIA will process it using the selected agent.

Configuration

Access settings via File > Preferences > Settings and search for “GAIA”:

Setting	Description	Default
`gaia.apiUrl`	GAIA API server URL	`http://localhost:8080`
`gaia.defaultModel`	Default GAIA model to use	`gaia-code`

Commands

The extension provides the following commands via the Command Palette:

GAIA: Manage API Server: Shows information about GAIA, configuration, and links to documentation

Architecture

The extension implements VSCode’s LanguageModelChatProvider API to register GAIA as a language model provider.

Usage Examples

Code Development
Jira Operations

Using GAIA Code Agent

Select GAIA code from the model picker
In chat, type: “Create a function to calculate prime numbers”
GAIA will:
- Create the function
- Generate tests
- Run linting
- Save files to your workspace
- Report file paths in the response

Troubleshooting

"Failed to connect to GAIA API server"

Symptoms: Extension cannot reach the API serverSolutions:

Ensure the API server is running: gaia api start
Check the server URL in settings matches where the server is running
Verify the server is healthy: curl http://localhost:8080/health

"No models available"

Symptoms: Model picker doesn’t show GAIA modelsSolutions:

Ensure Lemonade Server is running: lemonade-server serve --ctx-size 32768
The API server needs to be running before selecting models
Check the GAIA output channel for error messages (View > Output > GAIA)
Try restarting VSCode

Server Configuration Issues

Symptoms: Custom host/port not workingSolutions:

Update the gaia.apiUrl setting to match your server configuration
Restart the API server on the configured address
Ensure firewall allows connections to the configured port

Agent-Specific Issues

Code Agent not working:

Ensure Lemonade context size is 32768 or higher
Check workspace has write permissions

Jira Agent not working:

Ensure Jira is configured (see Jira documentation)
Verify Jira credentials are set up correctly

MCP Client Integration

Overview

VSCode can also integrate with GAIA through the Model Context Protocol (MCP) server. This is an alternative approach that uses MCP client capabilities rather than the Language Model Provider API.

This is not a VSCode extension, but rather a client integration using MCP protocol

Prerequisites

Install GAIA Framework

Install GAIA

Start Lemonade Server

Running with appropriate context size

Start GAIA MCP Server

The MCP server must be running

Getting Started

Start Lemonade Server

lemonade-server serve --ctx-size 32768

Start the GAIA MCP Server

gaia mcp start

The server will run on http://localhost:8765 by default.

Configure MCP Client

Configure your MCP client in VSCode to connect to http://localhost:8765.

Test Connection

Test the MCP integration:

# List available tools
curl http://localhost:8765/tools

# Test a query
curl -X POST http://localhost:8765/chat \
  -H "Content-Type: application/json" \
  -d '{"query":"Hello GAIA"}'

Architecture

Available Tools

The MCP server exposes GAIA agents as tools:

Tool	Description
`gaia.chat`	Conversational chat with context
`gaia.query`	Direct LLM queries (no context)
`gaia.jira`	Natural language Jira operations
`gaia.blender.create`	3D content creation

Configuration

MCP Server URL: http://localhost:8765 (default)
Protocol: JSON-RPC 2.0 + REST endpoints

For detailed MCP server documentation, see MCP Server Documentation.

Troubleshooting

Connection Issues

Symptoms: Cannot connect to MCP serverSolutions:

Verify MCP server is running: gaia mcp status
Start server if needed: gaia mcp start
Check server health: curl http://localhost:8765/health

Tool Not Available

Symptoms: Specific GAIA tool not showing upSolutions:

List available tools: curl http://localhost:8765/tools
Check server logs for errors
Ensure required agent dependencies are installed

Extension Development

This section covers developing and testing the GAIA VSCode extension (API Server approach).

Project Structure

src/vscode/gaia/
├── src/
│   ├── extension.ts          # Extension activation and commands
│   └── provider.ts            # LanguageModelChatProvider implementation
├── package.json               # Extension manifest and dependencies
├── tsconfig.json              # TypeScript configuration
└── .vscodeignore              # Files to exclude from package

Setup Development Environment

Node.js v20.19.x is required. See Prerequisites for installation instructions

Install Dependencies

cd src/vscode/gaia
npm install

Compile TypeScript

npm run compile

Or watch for changes:

npm run watch

Testing the Extension

Start Backend Services

Before testing, ensure the GAIA backend is running:

# Terminal 1: Start Lemonade Server
lemonade-server serve --ctx-size 32768

# Terminal 2: Start GAIA API Server
gaia api start

Launch Extension Development Host

Open the GAIA project root in VSCode
Go to Run > Start Debugging (F5)
Select “GAIA VSCode Extension (API)” from the launch configuration dropdown
This opens a new VSCode window (Extension Development Host) with the extension loaded

The launch configuration is defined in .vscode/launch.json and automatically compiles TypeScript before launching. There are two configurations:

GAIA VSCode Extension (API) - For testing with the GAIA API server (port 8080)
GAIA VSCode Extension (MCP) - For testing with the GAIA MCP server (port 8765)

Test the Provider

In the Extension Development Host window:

Open Command Palette (Ctrl+Shift+P)
Run “GAIA: Manage API Server” to see the About dialog
Open any chat feature (e.g., Copilot Chat if available)
Click the model picker
Select a GAIA model (gaia-code or gaia-jira)
Send a test message

Key Components

Extension Activation
Provider Implementation
Package Configuration

extension.ts

Registers the GAIA LanguageModelChatProvider
Implements management command for About dialog
Creates output channel for logging

provider.tsImplements VSCode’s LanguageModelChatProvider interface:

provideLanguageModelChatInformation: Fetches available models from API server
provideLanguageModelChatResponse: Handles chat requests with SSE streaming
provideTokenCount: Estimates token count for input

package.json

Declares languageModelChatProviders contribution
Registers commands and settings
Specifies activation events

API Integration

The extension communicates with the GAIA API server (see API documentation):

GET /v1/models

Returns list of available GAIA models with metadata.

POST /v1/chat/completions

Sends chat requests. Supports streaming via Server-Sent Events (SSE).

Building for Distribution

Install VSCE

npm install -g @vscode/vsce

Package Extension

cd src/vscode/gaia
vsce package

This creates gaia-vscode-0.1.0.vsix.

Install Locally

code --install-extension gaia-vscode-0.1.0.vsix

Debugging

The extension logs to the “GAIA” output channel. View it via: View > Output > Select “GAIA” from dropdown

Common Development Issues

“Failed to connect to GAIA API server” during development
- Check API server is running: curl http://localhost:8080/health
- Check gaia.apiUrl setting in Extension Development Host
Models not appearing in picker
- Ensure API server returns models: curl http://localhost:8080/v1/models
- Check VSCode output channel for errors
- Restart Extension Development Host
Streaming not working
- Verify API server supports SSE streaming
- Check network tab in browser developer tools (if testing web)
TypeScript compilation errors
- Run npm install to ensure dependencies are installed
- Check tsconfig.json configuration
- Verify VSCode TypeScript version matches project
Extension not loading in debugger
- Ensure you selected the correct launch configuration: “GAIA VSCode Extension (API)”
- Check that pre-launch task compiled successfully
- Look for errors in Debug Console

Architecture Details

Message Flow
Model Discovery

Testing Checklist

Before submitting changes:

TypeScript compiles without errors: npm run compile
Extension activates without errors
Models appear in model picker
Chat completions work (non-streaming)
Streaming responses work
About dialog displays correctly
Settings are respected
Error messages are clear and helpful
Output channel shows useful logs

Contributing

When making changes to the extension:

Update TypeScript code in src/
Run npm run compile to build
Test using the “GAIA VSCode Extension (API)” launch configuration
Update this documentation if adding features
Follow existing code style and patterns
Ensure copyright headers are present

Comparison: Extension vs MCP Integration

Feature	VSCode Extension (API)	MCP Integration
Integration Type	VSCode Extension	MCP Client
Protocol	OpenAI-compatible REST + SSE	JSON-RPC + REST
Port	8080	8765
Exposes	Agents as “models”	Agents as “tools”
Model Picker	✅ Yes	❌ No
Setup Complexity	Install extension	Configure MCP client
Launch Config	”GAIA VSCode Extension (API)"	"GAIA VSCode Extension (MCP)“
Best For	Language model provider workflow	MCP client workflow

GAIA API Server

OpenAI-compatible API server

GAIA MCP Server

Model Context Protocol server

Code Agent

Code agent capabilities

Jira Agent

Jira agent capabilities

Development Guide - GAIA framework setup
VSCode Language Model API - Official VSCode docs

Integrations

Packaging & Distribution

​GAIA VSCode Integration

​Overview

VSCode Extension

MCP Integration

​VSCode Extension (API Server)

​Overview

​Features

​Prerequisites

​Getting Started

​Configuration

​Commands

​Architecture

​Usage Examples

​Troubleshooting

​MCP Client Integration

​Overview

​Prerequisites

​Getting Started

​Architecture

​Available Tools

​Configuration

​Troubleshooting

​Extension Development

​Project Structure

​Setup Development Environment

​Testing the Extension

​Key Components

​API Integration

​GET /v1/models

​POST /v1/chat/completions

​Building for Distribution

​Debugging

​Architecture Details

​Testing Checklist

​Contributing

​Comparison: Extension vs MCP Integration

​See Also

GAIA API Server

GAIA MCP Server

Code Agent

Jira Agent

GAIA VSCode Integration

Overview

VSCode Extension (API Server)

Overview

Features

Prerequisites

Getting Started

Configuration

Commands

Architecture

Usage Examples

Troubleshooting

MCP Client Integration

Overview

Prerequisites

Getting Started

Architecture

Available Tools

Configuration

Troubleshooting

Extension Development

Project Structure

Setup Development Environment

Testing the Extension

Key Components

API Integration

GET /v1/models

POST /v1/chat/completions

Building for Distribution

Debugging

Architecture Details

Testing Checklist

Contributing

Comparison: Extension vs MCP Integration

See Also