Skip to content

Cursor IDE Setup

Cursor is an AI-native code editor built on VS Code that deeply integrates large language models into the editing experience. When combined with project-specific Cursor rules, it becomes a powerful accelerator for building Gaia applications — the AI understands your API patterns, project structure, and coding conventions out of the box.

Why Cursor for Gaia Development?

Benefit Description
Context-aware generation Cursor reads your entire project, so it understands your GaiaClient, FastAPI routes, and React components.
Custom rules .cursor/rules/ files teach the AI your project's conventions — Gaia auth patterns, endpoint shapes, error handling.
Inline editing Select code, press Cmd+K, describe what you want, and the AI rewrites it in place.
Chat with codebase Ask questions about your code in the sidebar — "How does the streaming endpoint work?" — and get answers grounded in your actual source.
VS Code compatible All your existing VS Code extensions, keybindings, and settings work.

Not required

Cursor is recommended but not required. Everything in this guide works with any editor. The Cursor rules are a bonus that accelerates development.

Installing Cursor

macOS

Bash
# Download from the website
open https://cursor.sh

# Or install via Homebrew
brew install --cask cursor

Linux

Download the AppImage from cursor.sh and make it executable:

Bash
chmod +x cursor-*.AppImage
./cursor-*.AppImage

Windows

Download the installer from cursor.sh and run it.

Verify Installation

Open Cursor and verify that the AI features are available by pressing Cmd+L (macOS) or Ctrl+L (Windows/Linux) to open the AI chat panel.

Opening the Project

Open the build-with-gaia project root in Cursor:

Bash
cursor /path/to/build-with-gaia

Or use File > Open Folder and select the project directory.

Open the root, not a subdirectory

Open the build-with-gaia/ root so Cursor can see both backend/ and frontend/ directories, plus the .cursor/rules/ that teach it your conventions.

Understanding .cursor/rules/

The .cursor/rules/ directory at the root of your project contains rule files (.mdc format) that provide context to Cursor's AI. Think of them as a persistent system prompt that's always active when you're working in this project.

Text Only
build-with-gaia/
├── .cursor/
│   └── rules/
│       ├── gaia-api-patterns.mdc       # Gaia API conventions & endpoints
│       ├── gaia-fastapi-backend.mdc    # FastAPI backend patterns
│       ├── gaia-react-frontend.mdc     # React frontend patterns
│       └── gaia-project-setup.mdc      # Project structure & setup
├── backend/
├── frontend/
└── ...

When you ask Cursor to generate code or answer questions, it automatically includes relevant rules as context. This means:

  • Generated FastAPI routes follow the project's auth and error-handling patterns.
  • React components use the correct API client and state management approach.
  • New files are placed in the right directories with the right imports.

Gaia-Specific Rules Included

This project ships with four rules tailored to Gaia development:

gaia-api-patterns.mdc

Teaches the AI about the Gaia API itself:

  • Authentication via API key header
  • Available endpoints (/ask, /ask/stream, /ask/exhaustive, /datasets, etc.)
  • Request/response shapes with Pydantic models
  • Conversation management patterns
  • Error response structure

gaia-fastapi-backend.mdc

Guides backend code generation:

  • FastAPI project structure (app/routes/, app/services/, app/models/)
  • How to initialize and use GaiaClient as a dependency
  • Session management patterns
  • Streaming response implementation with StreamingResponse
  • Error handling middleware

gaia-react-frontend.mdc

Guides frontend code generation:

  • Component structure and naming conventions
  • API client setup with fetch or axios
  • SSE streaming consumption with EventSource or fetch + ReadableStream
  • State management patterns for chat interfaces
  • TypeScript type definitions matching backend responses

gaia-project-setup.mdc

Covers project scaffolding:

  • Directory structure for a full-stack Gaia app
  • Required dependencies (Python and Node)
  • Environment variable setup
  • Docker configuration
  • Development workflow

Using Cursor's AI Features

Inline Edit — Cmd+K

Select a block of code, press Cmd+K, and describe what you want:

"Add error handling for GaiaAuthError and GaiaRateLimitError"

Cursor rewrites the selected code in place, following the patterns defined in your rules.

AI Chat — Cmd+L

Open the chat panel and ask questions about your codebase:

"How does the /api/ask endpoint handle streaming responses?"

The AI reads your actual source code and answers with references to specific files and line numbers.

Context References — @

In both inline edit and chat, use @ to explicitly reference files, directories, or symbols:

Reference Example What It Does
@file @backend/app/routes/ask.py Includes the full file as context
@folder @backend/app/ Includes all files in the directory
@symbol @GaiaClient Includes the class/function definition
@rules @.cursor/rules/ Explicitly references the Cursor rules
@docs @docs/ Includes documentation files

Be specific with @ references

The more specific your context references, the better the AI's output. Instead of @backend/, use @backend/app/routes/ask.py when you're working on the ask endpoint.

Composer — Cmd+Shift+I

For larger changes that span multiple files, use Composer. Describe the feature at a high level:

"Add a new endpoint /api/datasets/{name}/documents that lists all documents in a dataset, with a corresponding React page that displays them in a table."

Composer generates changes across multiple files in a single operation.

Tips for Effective AI-Assisted Gaia Development

Start with the Rules

Before asking Cursor to generate anything, verify the .cursor/rules/ directory is present. The rules make the difference between generic code and Gaia-aware code.

Be Specific About Gaia Patterns

When prompting, mention Gaia-specific concepts:

  • "Use the GaiaClient.ask_stream method with SSE streaming" — not just "add streaming"
  • "Follow the session auth pattern from the backend rules" — not just "add auth"
  • "Use the ExhaustiveSearchResponse model with pagination" — not just "add search"

Generate Backend Before Frontend

The backend defines the API contract. Generate routes and models first, then have Cursor generate React components that consume those exact endpoints.

Review Everything

AI-generated code is a starting point. Always review:

  • Auth patterns — ensure API keys aren't exposed to the frontend
  • Error handling — check that all error paths return structured responses
  • Type safety — verify Pydantic models match the actual Gaia API responses
  • Edge cases — streaming disconnection, empty results, timeout handling

Iterate in Small Steps

Rather than asking for an entire feature at once, build incrementally:

  1. Generate the route handler
  2. Add error handling
  3. Add the service layer
  4. Generate the React component
  5. Connect everything and test

Next Steps