AI Assistant

Built-in chat assistant that answers questions about your documentation.

Overview

The AI assistant adds a chat dialog to your documentation site. Users can click the sparkle icon in the header to open the dialog and ask questions about the documentation content.

The assistant uses the full documentation text (generated by the llms.txt integration) as context, so it can answer questions about any page on the site.

Enabling the Assistant

Set aiAssistant to true in src/config/settings.ts:

export const settings = {
  aiAssistant: true,
  // ...
};

When enabled:

• A sparkle icon appears in the header bar
• The @astrojs/node adapter is added automatically (the site switches from static to hybrid mode)
• The POST /api/ai-chat endpoint becomes available

Environment Setup

Create a .env file (see .env.example):

# "local" uses Claude Code CLI, "remote" uses Anthropic API
AI_CHAT_MODE=local

Local Mode

Uses the Claude Code CLI (claude -p) as the backend. No API key needed — uses your existing Claude Code authentication.

AI_CHAT_MODE=local

This is the simplest setup for local development.

Remote Mode

Calls the Anthropic Messages API directly. Requires an API key.

AI_CHAT_MODE=remote
ANTHROPIC_API_KEY=sk-ant-...

Uses claude-haiku-4-5-20251001 for fast, low-cost responses.

Chat Dialog

The dialog is a React island (src/components/ai-chat-modal.tsx) using the native <dialog> element.

Layout

• Narrow viewports (below lg/1024px): Full viewport width and height
• Wide viewports (1024px and above): Centered, 90vw/90vh with a max width of 52.5rem, with a border

Features

• Balloon-style message bubbles (user on right, assistant on left)
• Markdown rendering in assistant responses (bold, italic, code, lists, links)
• “Thinking…” indicator during API calls
• Error messages displayed inline
• Backdrop click or Escape to close
• Conversation resets on close

MSW Mock (Development Only)

For UI development without a real backend, enable MSW (Mock Service Worker). MSW is dev-only — it never runs in production builds.

Setup:

1. Generate the service worker file (one-time):

   npx msw init public/ --save

2. Set the environment variable:

   PUBLIC_ENABLE_MOCKS=true

3. Run the dev server (pnpm dev).

The mock handler (src/mocks/handlers.ts) returns a predefined response with a simulated delay. This is useful for styling and testing the chat UI without consuming API credits.

API Reference

For the full endpoint specification (request/response types, error codes, environment variables), see the AI Assistant API reference.

Cloudflare Worker (Standalone API)

For deploying the chat API as a standalone Cloudflare Worker (separate from the Astro site), see the packages/ai-chat-worker/ sub-package. The Worker fetches llms-full.txt from your deployed documentation site and uses it as context for Claude API calls — useful when you want to host the API independently or deploy the docs as a static site.

File Structure

src/
├── components/
│   ├── ai-chat-modal.tsx       # React island — chat dialog UI
│   └── mock-init.tsx           # MSW initializer (dev only)
├── mocks/
│   ├── handlers.ts             # MSW mock response handlers
│   ├── browser.ts              # MSW browser worker setup
│   ├── server.ts               # MSW node server setup
│   └── init.ts                 # Conditional MSW initialization
├── pages/
│   └── api/
│       └── ai-chat.ts          # Server endpoint (local/remote modes)
├── types/
│   └── ai-chat.ts              # ChatMessage, AiChatRequest/Response types
└── utils/
    └── render-markdown.ts      # Lightweight markdown-to-HTML renderer