ai-ads-agent

AI Ads Agent

A senior AI ads agent in your terminal.
Built by GoMarble.

A senior AI ads agent at your fingertips. Meta strategists, Google Ads specialists, creative-fatigue analysts, GA4 attribution experts, Shopify ops leads — each a specialized agent with battle-tested processes, not a generic chatbot.

AI Ads Agent is the AI ads agent for Claude Code & Codex CLI — it plugs your terminal into your ad accounts and turns it into a senior performance marketer across Google Ads, Meta, TikTok, LinkedIn, Bing, GA4, Shopify, Klaviyo & Search Console. Built by GoMarble, the team that runs paid media for some of the fastest-growing DTC brands.

• 🔌 Live ad-platform data via the GoMarble MCP server — OAuth, one-click sign-in
• 🧠 36 expert-authored skills — Google Ads, Meta (Facebook/Instagram), GA4, Shopify, Search Console, Klaviyo, TikTok, LinkedIn, Bing Ads, document generation
• ⚡ 8 morning-workflow slash commands — daily audits and decision matrices for Meta + Google
• 🛡️ Built-in guardrails — no synthetic data, no fabricated keywords, proper attribution discipline

Install

Claude Code

In a Claude Code session, paste these three commands:

/plugin marketplace add https://github.com/gomarble-ai/ai-ads-agent.git
/plugin install ai-ads-agent@ai-ads-agent
/reload-plugins

Using the full HTTPS URL (not the owner/repo shorthand) avoids SSH-key errors on machines where git is configured to rewrite GitHub HTTPS URLs to SSH.

Then connect the MCP server:

/mcp

Pick gomarble, click Authenticate — the browser opens, you sign in to GoMarble, you're done.

Codex CLI

codex plugin marketplace add https://github.com/gomarble-ai/ai-ads-agent.git

Start Codex, open the Plugins panel, find AI Ads Agent, and install. Then:

codex mcp login gomarble

Same OAuth flow, one-time.

One-command install for both (via npm)

npx ai-ads-agent

This wraps the official commands above and works on macOS / Linux / Windows.

🗣️ What you can ask the agent

The skills auto-invoke based on what you ask — you don't have to remember anything. Some examples:

Ask	What happens
"Audit my Meta account act_12345 for the last 30 days."	Loads performance + creative + depth-of-analysis skills, pulls 30d data, runs Pareto analysis, flags fatiguing creatives, surfaces ROAS outliers, produces a report.
"How did my Google Ads Search campaigns do this week?"	Loads search-analysis skill, classifies queries Q1–Q5, diagnoses CPC inflation or rank pressure, returns a decision matrix.
"Create a Meta ad set for this creative targeting US iOS users."	Loads create/master + adset skills, verifies parent campaign, detects pixel, builds the propose payload, asks you to confirm before posting.
"Pull a 7d Shopify sales report and compare to GA4 conversions."	Loads Shopify order-discipline + GA4 source-of-truth skills, queries both, reconciles the difference.
"Generate a PPTX summarizing all my paid-media performance."	Loads pptx skill + the relevant analytics skills, produces a deck.

⚡ Slash commands (Claude Code only)

8 read-only morning-workflow commands. Each produces analysis + recommendations — never executes mutations. Mutations happen separately via Agent Mode if the user explicitly opts in. Click any command name to view its source.

📊 Meta (4)

Command	What it does
/ai-ads-agent:meta-daily-optimization <acct>	Morning briefing: 1D vs 3D vs 7D, change-log gate, root-cause action recommendations (pause / cut / reallocate / scale candidates)
/ai-ads-agent:meta-ads-audit <acct>	30-day comprehensive audit — pixel/CAPI, fatigue, audience split, ROAS outliers, budget allocation
/ai-ads-agent:meta-creative-fatigue-detection <acct>	Per-ad scoring (Healthy / Early Warning / Fatigued / Dead) with refresh recommendations
/ai-ads-agent:meta-creative-strategy <acct>	Winners + losers, pattern extraction, test plan, scaling plan, 12-creative production spec

🎯 Google (4)

Command	What it does
/ai-ads-agent:google-search-audit <acct>	Daily Search briefing: brand-vs-non-brand segmentation, CUT / FIX / SCALE recommendations
/ai-ads-agent:google-pmax-pulse <acct>	3d-vs-3d PMax anomaly check — Critical / Alert / Monitor classification, disciplined against overcorrection
/ai-ads-agent:google-search-term-audit <acct>	Forensic waste audit using 80/80 Pareto + campaign-relative triggers; suggested negative keywords and root negatives
/ai-ads-agent:google-impression-share <acct>	Lost-IS analysis → scaling opportunities (Budget) vs bid/quality work (Rank), gated on profitability

In Codex, just describe the task in natural language — the skills' description fields handle routing.

📦 Skills shipped (36)

Click any skill name to view its SKILL.md source.

🎯 Google Ads (17)

Type	Skill	What it does
🏗️ Foundations	google-ads-tool-fundamentals	Tool-call patterns, GAQL basics, account structure
🏗️ Foundations	google-ads-guardrails	Mutation safety, attribution rules, what never to fabricate
🔍 Analysis	google-ads-search-analysis	Q1–Q5 query classification, CPC inflation diagnostics
🔍 Analysis	google-ads-shopping	Shopping / Merchant Center performance audits
🔍 Analysis	google-ads-pmax-evaluation	PMax 3d-vs-3d anomaly detection
🔍 Analysis	google-ads-pmax-scaling	PMax scaling decisions, disciplined against overcorrection
🔍 Analysis	google-ads-keywordplanner	Keyword discovery without fabrication
🔍 Analysis	google-ads-depth-of-analysis	Multi-layer drill-down methodology
⚡ Execution	google-ads-search-execution	Bid / budget / structure changes (gated on profitability)
🚀 Creation	google-ads-create-master-skill	Master orchestrator for new campaign builds
🚀 Creation	google-ads-create-campaign	Campaign-level setup
🚀 Creation	google-ads-create-ad-group	Ad-group creation
🚀 Creation	google-ads-create-ad	Ad-level creation
🚀 Creation	google-ads-create-asset	Asset uploads
🚀 Creation	google-ads-create-experiment	Experiment / draft setup
🚀 Creation	google-ads-create-negative-keyword-list	Negative-keyword list management
🚀 Creation	google-ads-create-bid-modifiers	Bid-modifier setup

📊 Meta — Facebook + Instagram (10)

Type	Skill	What it does
🏗️ Foundations	meta-tool-fundamentals	Tool-call patterns, account / campaign / ad-set / ad taxonomy
🏗️ Foundations	meta-guardrails	Mutation safety, attribution discipline
🔍 Analysis	meta-performance-analysis	Account-level performance audits
🔍 Analysis	meta-creative-analysis	Creative-fatigue scoring (Healthy / Warning / Fatigued / Dead)
🔍 Analysis	meta-depth-of-analysis	Multi-layer drill-down for Meta accounts
⚙️ Operations	meta-agent-operations	Agentic-loop patterns for Meta workflows
🚀 Creation	meta-create-master-skill	Master orchestrator for new Meta campaign builds
🚀 Creation	meta-create-campaign	Campaign-level setup
🚀 Creation	meta-create-adset	Ad-set setup
🚀 Creation	meta-create-ad-with-creative	Ad + creative pairing

📈 Other platforms (4)

Platform	Skill	What it does
📊 GA4	ga4-source-of-truth	Conversions ≠ transactions, channel-subset-sum traps, attribution discipline
🛍️ Shopify	shopify-order-discipline	No financial_status filter, gross-vs-net, refunds, multi-currency
🔎 Search Console	search-console-master-skill	Organic search analysis + opportunity scoring
🎨 Creative	creative-research	Competitor research, evergreen + breakout winners, pattern analysis

📄 Document generation (5)

Format	Skill	What it does
📝 DOCX	documents-docx-skill	Word document generation
🎯 PPTX	documents-pptx-skill	PowerPoint deck generation
📑 PDF	documents-pdf-skill	PDF report generation
📊 XLSX	documents-xlsx-skill	Excel spreadsheet generation
🐍 Python	python-sandbox-skill	Foundation for all document generation

🔄 How it works

You ask:  "Audit my Meta account"
    ↓
Claude / Codex auto-invokes the right skills by description
    ↓
Skill instructs the agent to call GoMarble MCP tools (meta_get_account_insights, etc.)
    ↓
GoMarble MCP → live Meta Ads API call (with your OAuth token)
    ↓
Agent applies the methodology + guardrails to interpret the data
    ↓
You get the answer

The plugin ships only the methodology. All live data comes from the GoMarble MCP server you authorized with /mcp (Claude) or codex mcp login gomarble.

🔁 Updating

# Claude Code
/plugin marketplace update ai-ads-agent

# Codex CLI
codex plugin marketplace update ai-ads-agent

The SessionStart hook also surfaces an "update available" prompt automatically the first time you start a session on an outdated version.

📁 Repo layout

This is what gets installed when you run any of the install commands above:

ai-ads-agent/
├── .claude-plugin/
│   ├── plugin.json              # Claude Code manifest
│   └── marketplace.json         # marketplace declaration
├── .codex-plugin/
│   └── plugin.json              # Codex manifest with rich install metadata
├── .mcp.json                    # remote MCP wiring (Streamable HTTP + OAuth)
├── commands/                    # 8 slash commands (Claude reads; Codex ignores)
├── hooks/
│   ├── hooks.json               # registers SessionStart hook
│   └── session-start.mjs        # MCP probe + version check + today's-date injection
├── skills/                      # 36 SKILL.md folders — both hosts read from here
└── README.md

Why one folder works for both hosts

Each host looks for its manifest in a dedicated subfolder; everything else is shared.

Host	Manifest	Reads	Ignores
Claude Code	.claude-plugin/plugin.json	skills/, commands/, .mcp.json (mcpServers key)	.codex-plugin/
Codex	.codex-plugin/plugin.json	skills/, .mcp.json (mcp_servers key)	.claude-plugin/plugin.json, commands/

.mcp.json ships both wrapper keys with identical content so each host finds its preferred form.

Support

• Docs & examples: https://gomarble.ai
• Issues & feature requests: https://github.com/gomarble-ai/ai-ads-agent/issues
• Account / billing: https://apps.gomarble.ai

Built with care by GoMarble
_{The AI ads agent for performance marketers — Google Ads, Meta, TikTok, LinkedIn, Bing, GA4, Shopify, Klaviyo & more.}

_{© GoMarble. MIT licensed.}