OpenAds 🎯

  ██████╗ ██████╗ ███████╗███╗   ██╗ █████╗ ██████╗ ███████╗
  ██╔═══██╗██╔══██╗██╔════╝████╗  ██║██╔══██╗██╔══██╗██╔════╝
  ██║   ██║██████╔╝█████╗  ██╔██╗ ██║███████║██║  ██║███████╗
  ██║   ██║██╔═══╝ ██╔══╝  ██║╚██╗██║██╔══██║██║  ██║╚════██║
  ╚██████╔╝██║     ███████╗██║ ╚████║██║  ██║██████╔╝███████║
   ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚═════╝ ╚══════╝

  AI Command Center for Marketers

Talk to your ad campaigns in plain English. Connect your Google Ads, Google Analytics (GA4), and Meta accounts, pick your favorite AI model, and let OpenAds handle the analysis while you focus on strategy.

What is OpenAds?

OpenAds is an open-source CLI tool that turns any AI model into a marketing assistant. It's built for performance marketers, media buyers, and growth leads who want to audit campaigns, write ad copy, and build strategies — all from one place.

No code. No prompt engineering. No spreadsheet exports.

Why use it?

| Feature | What it means for you | |---|---| | 🧠 Pre-built marketing skills | The AI already knows Google Ads best practices, Meta creative formats, CRO frameworks, and copywriting rules. You just ask. | | 🔌 Direct platform access | Connect your Google Ads, Google Analytics (GA4), and Meta accounts. The AI reads your live data — no more copy-pasting reports. | | 🤖 Bring your own model | Use Google Gemini, OpenAI, Claude, or a local model running on your machine. Your choice. | | 🛡️ Nothing goes live without you | The AI can read freely, but every write operation (campaign change, budget edit) requires your explicit approval. | | ⚡ Three experience tiers | Express for local models, Standard for mid-tier, Full for frontier — the same beautiful UI adapts its depth to your model's capability. |

⚡ Three Experience Tiers — One Beautiful Interface

OpenAds automatically adapts its entire experience based on your AI model's capability. Same menus, same polish, fundamentally different depth.

┌────────────────────────────────────────────────────────────┐
│  ⚡ Express          📊 Standard          🚀 Full         │
│  Llama 8B            Gemini Flash          GPT-4o          │
│  Mistral 7B          GPT-4o Mini           Claude Sonnet   │
│  Phi-3               Llama 70B             Gemini Pro      │
├────────────────────────────────────────────────────────────┤
│  System prompt:      System prompt:        System prompt:  │
│  ~150 words          ~300 words            ~500 words      │
│                                                            │
│  Skills: compact     Skills: full          Skills: full    │
│  (~100 words each)   (~400 words each)     + advanced      │
│                                                            │
│  MCP tools: none     MCP tools: 6          MCP tools: 11   │
│  (context-based)     (read-only)           (read + write)  │
│                                                            │
│  Menu: 7 items       Menu: 9 items         Menu: 10 items  │
│  AR: 4 commands      AR: 8 commands        AR: 12 commands │
│                                                            │
│  Output: bullets     Output: tables        Output: deep    │
│  & quick tables      & structured          analysis with   │
│                      reports               cross-platform  │
└────────────────────────────────────────────────────────────┘

Why tiers matter

A marketing manager running Llama 3.1 8B locally shouldn't get a worse experience — they should get a different but equally polished experience. Express mode delivers:

• Fewer menu items → less decision fatigue
• Compact skill files → the model follows instructions reliably
• No MCP tool chains → no multi-step failures
• Structured output templates → consistent, useful results every time

When you're ready for more depth, just run openads → Settings → Change experience tier.

📸 Screenshots

Here is a look at OpenAds in action:

⚡ Quick Start

👶 New to the terminal? Start here!

OpenAds is a local desktop application that runs in your computer's Terminal (a text-based window where you can run commands). Follow these simple steps to get started:

Step 1: Install Node.js (Required)

OpenAds runs on your computer using Node.js. If you don't have it yet, installing it is just like any normal application:

1. Go to nodejs.org and click the LTS (Recommended) button to download it.
2. Open the downloaded file and run the installer (just click "Next" until it finishes).

Step 2: Open your Terminal

• Mac: Press Cmd + Space (Spotlight search), type Terminal, and press Enter.
• Windows: Press the Windows Key on your keyboard, type cmd (Command Prompt), and press Enter.

Step 3: Install OpenAds

Copy the command below, paste it into your Terminal window, and press Enter:

npm install -g openads-ai

💡 Permissions Error? If your Terminal shows a red error about "EACCES" or permissions, copy and paste this command instead: sudo npm install -g openads-ai (Mac will ask you to type your computer password and press Enter).

Step 4: Run the Setup Wizard

Paste this command into your Terminal and press Enter:

openads setup

This launches a 6-step interactive setup wizard where you can:

• Select your AI model (Google Gemini, OpenAI, Claude, or a free local model)
• Choose your experience tier (Express ⚡, Standard 📊, or Full 🚀 — auto-recommended based on your model)
• Set your operational mode (Audit for read-only safety, or Launch for active campaign changes)
• Link your ad accounts (Google Ads, GA4, and/or Meta Ads)
• Describe your business (so the AI writes copy tailored exactly to your brand)

Step 5: Start using OpenAds!

Whenever you want to audit your campaigns or write copy, just open your Terminal, type:

openads

and press Enter to open your dashboard.

💻 Already know how to use the terminal? Quick commands

If you're already familiar with node packages, just run:

npm install -g openads-ai
openads setup
openads

🏠 Want to run 100% locally and offline?

# 1. Install Ollama (free, open-source)
brew install ollama     # Mac
# or: curl -fsSL https://ollama.com/install.sh | sh  # Linux

# 2. Pull a model
ollama pull llama3.1

# 3. Install OpenAds and pick "Local AI" + "Express" in setup
npm install -g openads-ai
openads setup

# 4. Run — no internet required
openads

💡 What can I do with it?

Here are some real examples — just type what you need:

Ads

| You type | What happens | |---|---| | Audit my Google Ads account and flag budget waste | Reads your live campaign data, finds underperforming keywords, and tells you where you're losing money. | | My Meta ROAS dropped 30% this week — what changed? | Pulls your Meta Ads data, compares to the prior period, and pinpoints what shifted. | | Write a 30-second video ad script for TikTok | Generates a hook → story → CTA script formatted for vertical video with platform-specific timing. |

Copywriting

| You type | What happens | |---|---| | Write 5 Google Ads headlines for my product | Generates headlines under 30 characters using your product context, with multiple creative angles. | | Rewrite this landing page to be more persuasive | Applies PAS/AIDA frameworks, tightens the copy, and fixes benefit vs. feature balance. |

Strategy

| You type | What happens | |---|---| | Build a go-to-market plan for my Q3 launch | Produces a structured GTM playbook covering positioning, channels, budget, and timelines. | | Who are my top 3 competitors and what are they saying in their ads? | Analyzes competitor positioning, identifies messaging gaps, and recommends differentiation angles. | | Research my target audience for a B2B SaaS product | Builds a customer research brief: pain points, buying triggers, objections, and voice-of-customer language. |

Optimization

| You type | What happens | |---|---| | My landing page converts at 1.2% — how do I improve it? | Runs a CRO audit: checks message match, CTA placement, form length, and gives prioritized fixes. | | Set up an A/B test for my signup page headline | Designs a proper experiment with hypothesis, control vs. variant, sample size, and success criteria. | | Run autoresearch on my ad headlines overnight | The AI autonomously generates variants, scores them, keeps the best, and reports back in the morning. |

Post-Click

| You type | What happens | |---|---| | Write a 5-email welcome sequence for new signups | Creates a full drip sequence: delivery → value → story → objection handling → soft pitch. |

🔬 Autoresearch — Autonomous Marketing Loops

Autoresearch is OpenAds' marquee feature: an autonomous loop that generates, scores, and iterates on marketing hypotheses without you lifting a finger.

The menu adapts to your tier:

| Tier | Available Commands | What you get | |---|---|---| | ⚡ Express | Generate, Plan, Debug, Fix | 4 commands, flat menu, 2 loop cycles | | 📊 Standard | + Discover, Analyze, Ship | 8 commands, 5 phases, 3 loop cycles | | 🚀 Full | + Validate (Predict, Probe, Reason, Scenario) | 12 commands, 6 phases, 5 loop cycles |

Full tier exclusive: The Validate phase includes multi-persona debates (5 expert personas evaluate your idea), stress-tests (8 personas attack your brief), and adversarial reasoning on key strategy calls.

🧠 Memory — Gets Smarter Every Session

OpenAds remembers what it learns about your business. After each conversation, the AI appends key insights to a plain markdown file at ~/.openads/context/my-business.md:

• Your best-performing campaigns and creative angles
• Audience segments and buying triggers
• Budget constraints and seasonal patterns
• Competitor insights and positioning gaps

You can open and edit this file anytime — it's your data, not a black box. The longer you use OpenAds, the better its advice gets.

⏰ Scheduled Automations

Set up automated campaign checks that run in the background — no server required.

openads schedule

| Preset | Frequency | |---|---| | 📊 Daily campaign health check | Every day at 8 AM | | 💸 Budget pacing alert | Every 6 hours | | 📉 Performance drop alert | Twice daily (9 AM & 5 PM) | | 📋 Weekly performance report | Every Monday at 9 AM | | ⏰ Custom (describe in plain English) | You choose |

Reports are saved to ~/.openads/reports/ in both Markdown and premium HTML dashboard formats. You can view, list, and open your reports directly:

openads report            # List all generated reports
openads report [name]     # Open a beautiful HTML dashboard in your browser

Manage your schedules:

openads schedule          # Open the schedule manager
openads schedule list     # See active schedules
openads schedule remove   # Remove a schedule

Uses your OS scheduler (macOS launchd / Linux crontab) — works even when your terminal is closed.

🛡️ Dual-Mode Safety (Audit vs. Launch)

To align with our Radical Simplicity & Safety by Default principles, OpenAds operates in two visual modes to give you total control and peace of mind over your ad accounts:

• Audit Mode (Safe / Read-only — Recommended): Strict read-only guidelines. The AI can pull live campaign statistics, analyze keywords, find budget waste, and recommend landing page optimizations, but is entirely blocked from making active changes.
• Launch Mode (Read-Write): Active campaign changes. Authorizes write modifications (e.g. pausing campaigns, scaling bids, altering budgets, or testing ad creative) but strictly mandates a clear visual preview card and an explicit confirmation prompt (Y/N) before executing.

Configure your default mode anytime by running openads → Settings → Change operational mode.

🩺 Diagnostics

Run the built-in diagnostics to check your setup:

openads doctor

This verifies your config file, API keys, platform connections (live token checks), required tools like uvx, and local AI readiness (checks if Ollama is running and your model is available).

🔒 Security & Privacy

• Runs 100% locally. OpenAds is not a cloud service. Nothing leaves your machine except the API calls you authorize.
• No telemetry. We don't track usage, store data, or phone home.
• Your keys stay on disk. API keys and tokens are saved to ~/.openads/ on your hard drive. They never touch our servers.
• Explicit approval for all writes. The AI previews every campaign change before execution. Nothing goes live without your Y.

🗺️ Roadmap

Shipped ✅

• [x] Google Ads & GA4 integration via MCP
• [x] Meta Ads integration via MCP
• [x] Interactive setup wizard with live token verification
• [x] 24 pre-built marketing skills across 7 categories
• [x] 12 autonomous research loop commands (Autoresearch)
• [x] Published to npm (npm install -g openads-ai)
• [x] Memory system — AI learns about your business over time
• [x] Scheduled automations — daily health checks, budget alerts, weekly reports
• [x] Three experience tiers — Express ⚡ / Standard 📊 / Full 🚀
• [x] Express skill variants — compact 100-word skill files optimized for local models
• [x] Tier-aware menus, prompts, tool chains, and output depth
• [x] Local AI diagnostics — Ollama reachability, model availability checks
• [x] Settings quick-switch — change tier and mode without re-running setup

Coming Next 🔜

• [ ] Telegram/WhatsApp bot gateway — talk to your ads from your phone
• [ ] LinkedIn Ads integration
• [ ] TikTok Ads integration (leveraging their TikTok Ads MCP Server)
• [ ] Pinterest Ads integration (leveraging MCP Ecosystem)
• [ ] Visual report dashboards in the terminal
• [ ] Headless --print mode for CI/CD pipelines
• [ ] Community-contributed skill packs

🤝 Contributing

We want OpenAds to be the standard open-source tool for AI-assisted marketing. You don't need to be a developer to contribute — marketing playbooks and strategy templates are just as valuable as code.

Read CONTRIBUTING.md to get started.

Our Principles

1. Radical Simplicity — Non-technical marketers must feel at home. No forcing users to learn code, prompt engineering, or API error messages.
2. Marketers First — We design around marketing workflows (audits, copy, analysis), not software concepts.
3. Safety by Default — AI should never spend money or publish campaigns without human approval.
4. Model Parity — A $0 local model should deliver a polished experience, not a broken one. Express mode exists to make this real.

👥 Core Team

• Luiz Amorim — Creator & Maintainer (lamorim.net | LinkedIn)

License

MIT.

Built on Pi (MIT). Includes tools derived from adloop (MIT) by kLOsk. Marketing skills inspired by marketingskills (MIT) by Corey Haines. Memory and background automation concepts inspired by Hermes Agent by Nous Research. Token optimization proxy concepts inspired by RTK by rtk-ai.