🤖 Moltflare - AI Agent on Cloudflare Workers

An advanced AI-powered agent built on Cloudflare Workers, featuring persistent memory, dynamic Code Mode (Worker Loader), and deep integrations with Google Workspace, GitHub, and R2 storage.

✨ Features

🧠 Logic & Memory

• Dual-Brain: Support for OpenAI (GPT-4o) and Google Gemini 2.5 Flash.
• Vector Memory: Uses Cloudflare Vectorize to store and retrieve long-term memories.
• Auto-Learning: Automatically extracts facts from conversations ("User lives in NYC") and saves them.
• Isolation: Memory and files are namespaced per-user for complete data separation.

🏭 Code Mode

• Dynamic Execution: The agent can write and execute JavaScript code instantly using the Worker Loader API.
• Persistent Workers: Save code as "workers" that can be run on-demand or on a schedule (Cron).
• Secure Sandbox: Code runs in a secure, isolated context with no network access by default.

📊 Mission Control

• Kanban Board: A dedicated UI for tracking complex tasks (Todo, In Progress, Done).
• Autonomous "Think" Cycle: A cron job runs hourly to let the agent check its tasks and proactively work on them without user input.

🔌 Integrations

Integration	Capabilities
📧 Gmail	Read, send, and draft emails.
📅 Calendar	List upcoming events, schedule meetings.
🐙 GitHub	Create branches, open PRs, read/edit files, list repos.
📁 R2 Files	Upload, read, and delete files (User Isolated).
🌐 Browser	Take screenshots, read web pages (Puppeteer).
🔍 Workflow	Multi-step research workflows using Cloudflare Workflows.

---

🛠️ Prerequisites

1. Cloudflare Account: For Workers, Durable Objects, Vectorize, and R2.
2. OpenAI API Key: Primary intelligence.
3. Google Cloud Console Project (Optional): For Gmail/Calendar OAuth.
4. GitHub Token (Optional): For repository management.

---

🚀 Setup Guide

1. Clone & Install

git clone https://github.com/your-username/moltflare.git
cd moltflare
npm install

2. Environment Secrets

Create a .dev.vars file in the root directory. Do not commit this file.

# AI Providers
OPENAI_API_KEY=sk-...

# Google Integration (OAuth)
# Create credentials in Google Cloud Console -> APIs & Services -> Credentials
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:5174/auth/google/callback

3. Create Vectorize Index

Required for long-term memory.

npx wrangler vectorize create agent-memory-index --dimensions 768 --metric cosine

4. Create R2 Bucket

Required for file storage tools.

npx wrangler r2 bucket create clawdbot-files

5. Run Locally

Start the development server:

npm run dev

Open http://localhost:5174 in your browser.

6. Deploy

Deploy to Cloudflare's global network:

npm run deploy

---

📖 User Guide & Configuration

Agent Settings

Click the Gear Icon ⚙️ in the top-right corner of the chat interface to access settings:

• API Keys: enter your OpenAI (sk-...) or Google Gemini keys here. These are stored securely in the agent's private database.
• Model Selection: Toggle between gpt-4o and gemini-2.5-flash-preview.
• GitHub Token: Enter a Personal Access Token (PAT) with repo scope to enable GitHub tools.
• Google Connection: Click "Connect Google" to link your Gmail/Calendar (requires OAuth setup below).

Google OAuth Setup (Gmail & Calendar)

To enable the agent to manage your emails and calendar, you need to create a Google Cloud Project:

1. Go to the Google Cloud Console.
2. Create a New Project.
3. Go to APIs & Services > Library and enable:
   • Gmail API
   • Google Calendar API
4. Go to APIs & Services > OAuth consent screen:
   • Select External (or Internal if you have a Workspace).
   • Add userinfo.email, userinfo.profile, gmail.modify, calendar.events scopes.
   • Add your email as a Test User.
5. Go to APIs & Services > Credentials:
   • Create Credentials -> OAuth Client ID.
   • Application Type: Web Application.
   • Authorized Redirect URIs:
     • http://localhost:5174/auth/google/callback (Local)
     • https://your-worker-subdomain.workers.dev/auth/google/callback (Production)
6. Copy the Client ID and Client Secret into your .dev.vars file.

---

🔧 Tool Reference

The agent has access to the following tools defined in worker/tools/:

Use Case	Tools
Code	executeCode, saveWorkerCode, runSavedWorker, listSavedWorkers, deleteSavedWorker
Memory	saveMemory (auto-called), searchMemory
Files	listFiles, uploadFile, readFile, deleteFile (All isolated by Agent ID)
Google	listEmails, readEmail, sendEmail, listEvents, createEvent
GitHub	github_list_repos, github_create_pr, github_get_file, github_commit_file
Browser	screenshot, readPage
Tasks	createTask, updateTask, listTasks, deleteTask, scheduleTask
Research	startResearch (Triggers Workflow)

---

📦 Project Structure

moltflare/
├── src/                      # Frontend (React + Vite)
│   ├── app.tsx               # Main application logic
│   ├── components/           # Shadcn UI components
│   └── ...
├── worker/                   # Backend (Cloudflare Workers)
│   ├── server.ts             # Hono API Server
│   ├── chat-do.ts            # Durable Object (The Agent)
│   ├── system-prompt.ts      # Personality & Instructions
│   ├── tools.ts              # Tool Registry
│   ├── tools/                # Individual Tool Implementations
│   │   ├── code-executor.ts  # Worker Loader logic
│   │   ├── files.ts          # R2 logic (Isolated)
│   │   └── ...
│   └── workflows/            # Cloudflare Workflows
├── wrangler.jsonc            # Infrastructure Config
└── package.json

---

🛡️ Security Notes

• Secrets: API keys entered in the UI settings are stored in the Agent's secure Durable Object storage, never in the browser.
• File Isolation: The files.ts tool automatically prefixes all R2 keys with the Agent ID, ensuring users cannot access each other's files.
• Code Sandbox: Dynamic workers usually run with blocked network access to prevent abuse.

---

📄 License

MIT