An AI-powered creative advertising agent that generates conversion-focused ads using a hook-first methodology. Built with the Claude Agent SDK, it analyzes brand websites, extracts factual data, and creates 6 diverse ad concepts with AI-generated images.
- Hook-First Ad Generation - Hooks are mined from research data using proven formulas (hooks = 80% of ad performance)
- Research-Driven - Extracts real data from brand websites: offers, value props, proof points, testimonials
- 6 Diverse Concepts - Each concept uses a different emotional trigger (social proof, urgency, curiosity, etc.)
- AI Image Generation - Creates visuals via fal.ai Nano Banana Pro
- Session Management - Stateful conversations with forking for A/B testing
- Dual Deployment - Local development server + Cloudflare Workers production
┌─────────────────────────────────────────────────────────────┐
│ ORCHESTRATOR (Main Agent) │
│ │
│ ┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ │
│ │ research │ → │ hook-methodology │ → │ art-style │ │
│ │ (Agent) │ │ (Skill) │ │ (Skill) │ │
│ └─────────────┘ └──────────────────┘ └─────────────┘ │
│ ↓ ↓ ↓ │
│ research.md hook-bank.md prompts.json │
│ ↓ │
│ ┌─────────────┐ │
│ │ nano-banana │ │
│ │ (MCP/fal) │ │
│ └─────────────┘ │
│ ↓ │
│ 6 PNG images │
└─────────────────────────────────────────────────────────────┘
- Parse - Extract URL and brand name from request
- Research - Agent fetches homepage, extracts offers/value props/proof points
- Hooks - Skill generates 10+ hooks, selects 6 with diversity matrix
- Art - Skill creates visual prompts for each hook
- Images - MCP generates images via fal.ai
- Complete - Returns 6 ad concepts with images
- Node.js v20+
- Anthropic API Key
- fal.ai API Key
# Clone the repository
git clone https://github.com/DV0x/creative-ad-agent.git
cd creative-ad-agent
# Install server dependencies
cd server && npm install
# Create environment file
cp .env.example .env
# Edit .env with your API keys# Start the server
cd server
npm run dev
# Server runs at http://localhost:3001curl -X POST http://localhost:3001/generate \
-H "Content-Type: application/json" \
-d '{"prompt": "Create ads for https://example.com"}'creative-ad-agent/
├── agent/ # Agent ecosystem
│ └── .claude/
│ ├── agents/
│ │ └── research.md # Data extraction agent
│ └── skills/
│ ├── hook-methodology/
│ │ ├── SKILL.md # Hook generation skill
│ │ └── formulas.md # Hook formula reference
│ └── art-style/
│ ├── SKILL.md # Visual prompt skill
│ └── workflows/ # Style-specific workflows
│
├── server/ # Local Express server
│ ├── sdk-server.ts # Main server
│ └── lib/
│ ├── ai-client.ts # Claude SDK wrapper
│ ├── nano-banana-mcp.ts # fal.ai MCP integration
│ ├── session-manager.ts # Session handling
│ └── orchestrator-prompt.ts
│
├── client/ # React frontend
│ └── src/
│ ├── App.tsx
│ ├── hooks/useGenerate.ts
│ └── components/
│
├── creative-agent-cf/ # Cloudflare Workers deployment
│ ├── src/ # Worker code
│ └── sandbox/ # Container code
│
└── docs/ # Documentation
| Endpoint | Method | Description |
|---|---|---|
/generate |
POST | Generate ad campaign |
/health |
GET | Health check |
/sessions |
GET | List active sessions |
/sessions/:id |
GET | Get session info |
/sessions/:id/continue |
POST | Resume session |
/sessions/:id/fork |
POST | Fork for A/B testing |
/images/:session/:file |
GET | Serve generated image |
The system uses a research-first approach where every hook is traceable to specific data:
| Hook Type | Emotional Trigger | Example |
|---|---|---|
| Stat/Data | Social Proof | "847 homeowners saved $12,340 last year" |
| Story/Result | Empathy + Relief | "Sarah was paying $2,100/mo. Now she pays $1,650" |
| FOMO/Urgency | Loss Aversion | "Rates just dropped 0.5%. Lock yours before Friday" |
| Curiosity | Intrigue | "The 3-minute check that saved Mark $347/month" |
| Call-out | Recognition | "Toronto renters paying $2,500+: You could own for less" |
| Contrast/Enemy | Differentiation | "Banks want you confused. We want you approved" |
The default style is Soft Brutalism Clay - neo-brutalist borders with warm clay textures. Additional workflows available:
soft-brutalism-clay.md- Defaultanderson-clay-diorama.md- Wes Anderson-inspired theatrical scenes
cd creative-agent-cf
# Set secrets
wrangler secret put ANTHROPIC_API_KEY
wrangler secret put FAL_KEY
# Deploy
npm run deploySee docs/cloudflare-deployment-plan.md for detailed instructions.
cd client
npm install
npm run dev
# Opens at http://localhost:5173Features:
- Real-time SSE streaming
- Phase progress indicators
- Terminal-style log output
- Image gallery with lightbox
| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Yes | Claude API key |
FAL_KEY |
Yes | fal.ai image generation key |
PORT |
No | Server port (default: 3001) |
CLAUDE_CODE_MAX_OUTPUT_TOKENS |
No | Token limit (default: 16384) |
- ARCHITECTURE.md - Complete system architecture
- docs/cloudflare-deployment-plan.md - Cloudflare deployment
- docs/frontend-design-system.md - UI design specs
- docs/LESSONS_LEARNED.md - Development insights
- Runtime: Node.js, TypeScript
- AI: Claude Agent SDK, Claude Opus 4.5
- Images: fal.ai Nano Banana Pro
- Server: Express.js
- Client: React, Zustand, Vite, Tailwind CSS
- Production: Cloudflare Workers + Sandbox
Contributions are welcome! Please read the existing code patterns and ensure your changes follow the hook-first methodology philosophy.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT License - see LICENSE for details.
- Built with Claude Agent SDK
- Image generation by fal.ai
- Hook methodology inspired by conversion copywriting principles
