Creative Ad Agent

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.

Features

• 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

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    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      │
└─────────────────────────────────────────────────────────────┘

Workflow

1. Parse - Extract URL and brand name from request
2. Research - Agent fetches homepage, extracts offers/value props/proof points
3. Hooks - Skill generates 10+ hooks, selects 6 with diversity matrix
4. Art - Skill creates visual prompts for each hook
5. Images - MCP generates images via fal.ai
6. Complete - Returns 6 ad concepts with images

Quick Start

Prerequisites

• Node.js v20+
• Anthropic API Key
• fal.ai API Key

Installation

# 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

Running Locally

# Start the server
cd server
npm run dev

# Server runs at http://localhost:3001

Generate Ads

curl -X POST http://localhost:3001/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create ads for https://example.com"}'

Project Structure

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

API Endpoints

| 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 |

Hook Methodology

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" |

Art Styles

The default style is Soft Brutalism Clay - neo-brutalist borders with warm clay textures. Additional workflows available:

• soft-brutalism-clay.md - Default
• anderson-clay-diorama.md - Wes Anderson-inspired theatrical scenes

Cloudflare Deployment

cd creative-agent-cf

# Set secrets
wrangler secret put ANTHROPIC_API_KEY
wrangler secret put FAL_KEY

# Deploy
npm run deploy

See docs/cloudflare-deployment-plan.md for detailed instructions.

React Client

cd client
npm install
npm run dev

# Opens at http://localhost:5173

Features:

• Real-time SSE streaming
• Phase progress indicators
• Terminal-style log output
• Image gallery with lightbox

Configuration

| 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) |

Documentation

• 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

Tech Stack

• 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

Contributing

Contributions are welcome! Please read the existing code patterns and ensure your changes follow the hook-first methodology philosophy.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with Claude Agent SDK
• Image generation by fal.ai
• Hook methodology inspired by conversion copywriting principles