CloudflareMate

CloudflareMate is a polished, minimal AI assistant designed for users to ask questions about Cloudflare-specific knowledge, Workers, Agents, and other integrated expertise. It features a single-page, mobile-first React application built with Vite, running on Cloudflare Workers and Agents, with Durable Objects for conversation persistence. The app leverages existing ChatAgent and AppController endpoints to deliver a visually exceptional, accessible, and delightful user interface using shadcn/ui components and Tailwind CSS.

Key Features

• Elegant Conversational Interface: A beautiful, responsive single-page application with a hero section, session sidebar, main chat column, and composer.
• Advanced Session Management: Create, switch, rename, and delete chat sessions.
• Data Portability: Export individual sessions or all sessions as a JSON file. Import sessions from a file with conflict resolution.
• Session Tagging: Organize conversations with customizable tags (e.g., 'Cloudflare', 'Workers', 'AI Gateway').
• Streaming Responses: Real-time AI replies with a live typing effect for a dynamic user experience.
• Tool Integration: Displays results from tools like web search with expandable, inspectable details.
• User Preferences: Customize the default AI model, toggle streaming, and manage custom tags.
• Usage Awareness: A clear notice in the footer regarding shared AI request limits to manage user expectations.
• Responsive & Accessible: Designed mobile-first, ensuring a seamless experience on any device, with a focus on accessibility.

Technology Stack

• Frontend: React 18.x, Vite, Tailwind CSS v3, shadcn/ui, Framer Motion, Lucide React, Sonner (toasts), Zustand.
• Backend: Cloudflare Workers, Hono, Cloudflare Agents SDK (Durable Objects), OpenAI SDK (via Cloudflare AI Gateway), MCP SDK.
• Development: TypeScript, ESLint, Bun.

Multi-Model Support

CloudflareMate connects to various AI models through the Cloudflare AI Gateway. This allows you to seamlessly switch between different providers and models, such as:

• Google Gemini: gemini-2.5-flash, gemini-2.5-pro
• OpenAI: gpt-4o, gpt-3.5-turbo The model can be selected from the dropdown menu in the chat header. The application routes requests to the appropriate model via the AI Gateway, which handles authentication and provider specifics on the server side.

Quick Start

Prerequisites

• Bun installed.
• A Cloudflare account with Workers enabled.
• Environment variables configured for your Cloudflare account.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd cloudflaremate

2. Install dependencies:

   bun install

3. Configure Environment Variables: Create a .dev.vars file in the root directory or configure secrets in your Cloudflare dashboard.

   # .dev.vars
   CF_AI_BASE_URL="https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY_ID/openai"
   CF_AI_API_KEY="YOUR_CLOUFLARE_API_KEY"
   # Optional, for web_search tool
   SERPAPI_KEY="YOUR_SERPAPI_KEY"

4. Generate TypeScript types for Cloudflare bindings:

   bun run cf-typegen

Usage

Running Locally

Start the development server, which includes the Vite frontend and the local Wrangler server for the worker:

bun run dev

The application will be available at http://localhost:3000.

Key Interactions

• Start Chatting: Type a message in the composer. A new session is automatically created.
• Manage Sessions: Use the sidebar to create, switch, rename, delete, import, or export sessions.
• Inspect Tools: When the AI uses a tool, a badge will appear. Click it to open the Tool Inspector and view detailed inputs and outputs.
• Customize Settings: Click the settings icon in the composer to change the default model, toggle streaming, and manage your custom tags.

Troubleshooting

• Rate Limiting: The footer contains a notice about shared AI request capacity. If you encounter throttling, please wait and retry your request later. This is a global limit across all users of the AI Gateway.
• Streaming Errors: Occasionally, a streaming connection may be interrupted. The application will attempt to handle this gracefully, but if a response cuts off, you may need to resubmit your message.
• Model-Specific Behavior: Different models may have varying levels of performance, tool usage capabilities, and response styles. If you get an unsatisfactory answer, try switching to a different model.
• Session Persistence: Sessions are stored in Cloudflare Durable Objects. If you clear your browser's local storage, you will lose session tags and preferences, but the conversation history will remain on the server.

Deployment

1. Build the project:

   bun run build

2. Deploy to Cloudflare Workers:

   bun run deploy

This command bundles the worker and static assets, binds the Durable Objects, and deploys them to your Cloudflare account. Important: Ensure your environment variables (CF_AI_BASE_URL, CF_AI_API_KEY, SERPAPI_KEY) are set as secrets in your production Worker environment via the Cloudflare dashboard or wrangler secret put.