Skip to content

Claude Code Setup

Claude Code is Anthropic's agentic coding assistant for working directly in your terminal and repository. It is a strong fit for Gaia projects because it can reason across multiple files, run commands, and apply focused edits while keeping your architecture patterns intact.

Why Use Claude Code for Gaia Projects?

Benefit Description
Terminal-native workflow Works well for backend-heavy Gaia development, debugging, and deployment tasks.
Multi-file changes Handles coordinated edits across SDK, backend, frontend, and docs.
Repo-aware context Can use project conventions from a checked-in guidance file (CLAUDE.md).
Great for refactors Useful for repetitive updates across route handlers, models, and examples.

Complementary to Cursor

You can use Cursor for interactive editing and Claude Code for terminal-first tasks. Both workflows can share the same Gaia conventions.

Install Claude Code

Follow Anthropic's current install instructions in their docs:

After installation, verify the CLI works:

Bash
claude --help

Open This Project

Run Claude Code from the build-with-gaia project root so it has full context:

Bash
cd /path/to/build-with-gaia
claude

Use the repository root

Running from the root lets Claude Code reason across examples/, sdk/, docs/, and deployment scripts in one session.

Add Persistent Project Guidance (CLAUDE.md)

Claude Code works best when your repo contains a clear project guidance file. Add a CLAUDE.md at the project root and capture Gaia-specific patterns you want consistently followed.

Example starter structure:

Markdown
# Build With Gaia - Claude Code Guide

## Project Goals
- Build production-ready Gaia examples, SDK docs, and deployment assets.
- Keep docs and example code aligned.

## Architecture Rules
- Frontend never sends `GAIA_API_KEY`.
- Backend owns all Gaia API calls.
- Prefer async Python (`httpx`, FastAPI async endpoints).
- Keep request/response models explicit and typed.

## Gaia API Conventions
- Base URL from config/env, never hardcoded.
- Use established endpoint patterns from existing examples.
- Handle auth, rate limit, and upstream errors explicitly.

## Docs Conventions
- Update related docs pages when code behavior changes.
- Use internal links (not GitHub links) for local docs hosting.

## Deployment Conventions
- Use `scripts/publish-docs-azure.sh` for docs updates.
- Avoid full infra redeploys for content-only changes.

Prompting Patterns That Work Well

Feature Build

Text Only
Add a new FastAPI endpoint for [feature] in the same style as existing routes.
Use current Gaia client patterns and typed request/response models.
Then update the related docs chapter under docs/.

Safe Refactor

Text Only
Refactor [target files] to reduce duplication without behavior changes.
Keep public API responses identical.
Run the relevant checks and summarize any risks.

Docs + Code Sync

Text Only
Implement [change] in examples/04-gaia-mcp-server and update docs/examples/index.md
plus docs/05-advanced-topics/mcp-server.md so setup and behavior stay accurate.

Suggested Workflow

  1. Describe the task with file references and expected behavior.
  2. Constrain the scope ("edit only these files" if needed).
  3. Review diffs before accepting changes.
  4. Validate with quick checks (mkdocs build --strict, app run/tests).
  5. Document any behavior changes in the relevant docs chapter.

Gaia-Specific Safety Checklist

  • API keys remain server-side only.
  • No hardcoded tenant/environment secrets.
  • Error handling includes auth and rate-limit cases.
  • Streaming endpoints preserve SSE behavior.
  • Docs examples match actual file paths and commands.

Next Steps