Skip to content
Back to search

meta-ads-kit

Open source AI ad manager. Replace 20 min of Ads Manager with a 2-min briefing. Built with OpenClaw + social-cli.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/themattberman--meta-ads-kit/badge.svg)](/listings/themattberman--meta-ads-kit)

HTML

<a href="/listings/themattberman--meta-ads-kit"><img src="/api/listings/themattberman--meta-ads-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/themattberman/meta-ads-kit.git
cd meta-ads-kit

# Install Meta's official Ads CLI (Python 3.12+)
pip install meta-ads
# or use uvx without global install:
uvx --python 3.12 --from meta-ads meta --help

# Copy config and start safely in mock mode
cp .env.example .env
cp ad-config.example.json ad-config.json
META_KIT_MODE=mock ./scripts/meta-kit.sh doctor
META_KIT_MODE=mock ./run.sh daily-check

# For real read-only reports, set ACCESS_TOKEN + AD_ACCOUNT_ID in .env

See [SETUP.md](SETUP.md) for detailed instructions.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Meta Ads Copilot
  2. An open-source AI ad manager that replaces 20 minutes of Ads Manager clicking with a 2-minute summary over coffee.
  3. Built with [OpenClaw](https://openclaw.ai) — the AI agent framework.
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. [![OpenClaw](https://img.shields.io/badge/Built%20with-OpenClaw-blue)](https://openclaw.ai)
  6. ---
  7. **Monitor → Detect Fatigue → Find Winners → Shift Budget → Generate Copy → Upload to Meta → Repeat**
  8. This kit automates your entire Meta Ads workflow:
  9. - **Morning briefing** — Spend pacing, active campaigns, 7-day trends
  10. - **Find bleeders** — Ads with high spend + low CTR bleeding your budget
  11. - **Spot winners** — Top performers ready to scale
  12. - **Detect fatigue** — CTR declining, frequency climbing, CPC rising
  13. - **Generate copy** — AI writes ad copy matched to your actual image creatives
  14. - **Upload to Meta** — Prepare/upload ads through official CLI-first workflows where supported
  15. - **Pixel + CAPI audit** — Audit your tracking setup, test server-side events, optimize for 9.3+ Event Match Quality
  16. - **Take action** — Pause, resume, adjust budgets (always with your approval)
  17. The result: A full ad management loop -- from monitoring to creative refresh to tracking optimization -- without opening Ads Manager.
  18. ---
  19. ## Why This Exists
  20. I've spent 20 years in marketing. Scaled Fireball Whisky from one state to a billion-dollar global brand. Ran campaigns for Heineken, Hennessy, Buffalo Trace. Now I run [Emerald Digital](https://emerald.digital), an AI-first marketing agency.
  21. Here's what I learned: 90% of ad management is pattern recognition. Spend trending up or down. CTR declining (creative fatigue). CPA spiking (audience exhaustion). Winners emerging. Losers bleeding.
  22. You don't need to stare at Ads Manager to spot these patterns. An AI agent can do it and tell you what matters.
  23. I'm open-sourcing this because every founder running Meta ads deserves a copilot.
  24. ---
  25. ## Quick Start
  26. ```bash
  27. git clone https://github.com/themattberman/meta-ads-kit.git
  28. cd meta-ads-kit
  29. # Install Meta's official Ads CLI (Python 3.12+)
  30. pip install meta-ads
  31. # or use uvx without global install:
  32. uvx --python 3.12 --from meta-ads meta --help
  33. # Copy config and start safely in mock mode
  34. cp .env.example .env
  35. cp ad-config.example.json ad-config.json
  36. META_KIT_MODE=mock ./scripts/meta-kit.sh doctor
  37. META_KIT_MODE=mock ./run.sh daily-check
  38. # For real read-only reports, set ACCESS_TOKEN + AD_ACCOUNT_ID in .env
  39. ```
  40. See [SETUP.md](SETUP.md) for detailed instructions.
  41. ---
  42. ## The 5 Daily Questions
  43. The core of the system. Five questions that replace Ads Manager:
  44. | # | Question | What It Tells You |
  45. |---|----------|-------------------|
  46. | 1 | Am I on track? | Today's spend vs. pacing expectations |
  47. | 2 | What's running? | Active campaigns at a glance |
  48. | 3 | How's performance? | 7-day metrics by campaign |
  49. | 4 | Who's winning/losing? | Ad-level performance sorted |
  50. | 5 | Any fatigue? | CTR trends, frequency, CPC movement |
  51. ```bash
  52. # Run all 5 questions
  53. ./run.sh daily-check
  54. # Or with OpenClaw agent
  55. openclaw start
  56. # Then message: "Daily ads check"
  57. ```
  58. ---
  59. ## Skills
  60. | Skill | What It Does |
  61. |-------|-------------|
  62. | `meta-ads` | Core reporting — daily checks, campaign insights, bleeders, winners, fatigue detection |
  63. | `ad-creative-monitor` | Track creative performance over time, detect fatigue before it kills your ROAS |
  64. | `budget-optimizer` | Analyze spend efficiency, recommend budget shifts between campaigns/adsets |
  65. | `ad-copy-generator` | Generate ad copy matched to specific image creatives — analyzes the visual, writes copy that reinforces it, outputs `asset_feed_spec`-ready variants |
  66. | `ad-upload` | Prepare official CLI-first creative/ad upload payloads with PAUSED-only, dry-run-first guardrails |
  67. | `pixel-capi` | Audit Meta Pixel + Conversions API setup, test server-side events, optimize Event Match Quality to 9.3+. Platform guides for Next.js, Shopify, WordPress, Webflow, GHL, ClickFunnels |
  68. Each skill can run standalone or as part of the daily routine.
  69. ### The Full Loop
  70. The five skills chain together into a closed loop:
  71. ```
  72. Monitor (meta-ads) → Detect fatigue (ad-creative-monitor) → Shift budget (budget-optimizer)
  73. → Generate new copy (ad-copy-generator) → Prepare/upload PAUSED ads (ad-upload) → Monitor again
  74. Pixel + CAPI (pixel-capi) runs alongside: audit tracking, test server events, optimize EMQ
  75. ```
  76. No Ads Manager required at any step.
  77. ---
  78. ## How It Works
  79. ```
  80. ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
  81. │ Daily Check │───▶│ Patterns │───▶│ Budget │───▶│ Copy Gen │───▶│ Upload │
  82. │ (5 questions│ │ & Fatigue │ │ Optimizer │ │ (per image) │ │ (Ads CLI) │
  83. └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
  84. │ │ │ │ │
  85. ▼ ▼ ▼ ▼ ▼
  86. Spend pacing Bleeders 🩸 Shift budget Copy matched to Push ads live
  87. Active campaigns Winners 🏆 Scale winners each creative No Ads Manager
  88. 7-day trends Fatigue 😴 Cap losers asset_feed_spec Image + copy
  89. ```
  90. **Morning (automated via cron):**
  91. 1. Run daily-check — flag bleeders, winners, and fatigue
  92. 2. Send strategist-level briefing to Slack/Telegram with recommendations and new creative concepts
  93. 3. You approve from your phone
  94. **When you need new creatives:**
  95. 1. Generate copy matched to specific image creatives
  96. 2. Review the variants
  97. 3. Prepare a dry-run upload/create payload; approve before anything reaches Meta
  98. **You (2 minutes over coffee):**
  99. 1. Read the summary
  100. 2. Approve/reject recommendations
  101. 3. Done.
  102. ---
  103. ## Running With OpenClaw
  104. This kit is built for [OpenClaw](https://openclaw.ai), an open-source AI agent framework. Under the hood, reports route through `./run.sh` → `scripts/meta-kit.sh` → Meta's official Ads CLI (`meta`).
  105. ```bash
  106. # Install OpenClaw
  107. npm install -g openclaw
  108. # Set up the agent
  109. cd meta-ads-kit
  110. openclaw start
  111. ```
  112. Then just message it naturally:
  113. - "How are my ads doing?"
  114. - "Any bleeders I should pause?"
  115. - "Which ads should I scale?"
  116. - "Check for creative fatigue"
  117. - "Show me performance by age and gender"
  118. - "Pause ad 12345678"
  119. The agent handles orchestration, interprets the data, and asks before taking any spend-impacting action.
  120. ### Automate It
  121. Set up a daily cron in OpenClaw:
  122. ```
  123. "Run my daily ads check every morning at 8am and send me the summary"
  124. ```
  125. The agent will run the 5 questions, analyze the results, and message you with findings + recommendations. You approve from your phone.
  126. ---
  127. ## Configuration
  128. Edit `ad-config.json` to set your benchmarks:
  129. ```json
  130. {
  131. "account": {
  132. "id": "act_123456789",
  133. "name": "My Brand"
  134. },
  135. "benchmarks": {
  136. "target_cpa": 25.00,
  137. "target_roas": 3.0,
  138. "max_frequency": 3.5,
  139. "min_ctr": 1.0,
  140. "max_cpc": 2.50
  141. },
  142. "alerts": {
  143. "bleeder_ctr_threshold": 1.0,
  144. "bleeder_frequency_threshold": 3.5,
  145. "fatigue_ctr_drop_pct": 20,
  146. "spend_pace_alert_pct": 15
  147. },
  148. "reporting": {
  149. "default_preset": "last_7d",
  150. "timezone": "America/New_York"
  151. }
  152. }
  153. ```
  154. Or just tell the OpenClaw agent your benchmarks conversationally — it'll figure it out.
  155. ---
  156. ## Cost
  157. | Tool | Monthly Cost |
  158. |------|-------------|
  159. | Official Meta Ads CLI (`meta-ads`) | Free |
  160. | Meta API | Free (your own ad account) |
  161. | OpenClaw | Free (open source) |
  162. | **Total** | **$0/mo** |
  163. Your Meta ad spend is separate — this kit just helps you manage it smarter.
  164. ---
  165. ## Project Structure
  166. ```
  167. meta-ads-kit/
  168. ├── README.md # You're here
  169. ├── SETUP.md # Detailed setup guide
  170. ├── run.sh # Local adapter command router
  171. ├── scripts/ # meta-kit dispatcher, CLI wrapper, safety guards, fixtures
  172. ├── .env.example # Environment template
  173. ├── ad-config.example.json # Benchmarks template
  174. ├── skills/
  175. │ ├── meta-ads/ # Core reporting & recommendations
  176. │ ├── ad-creative-monitor/ # Creative fatigue tracking
  177. │ ├── budget-optimizer/ # Spend efficiency analysis
  178. │ ├── ad-copy-generator/ # AI copy matched to image creatives
  179. │ ├── ad-upload/ # Upload/create payload prep and guardrails
  180. │ └── pixel-capi/ # Pixel + CAPI audit, testing, EMQ optimization
  181. │ ├── scripts/ # pixel-audit, pixel-setup, capi-test, capi-send, emq-check
  182. │ └── references/ # Complete pixel + CAPI knowledge base
  183. ├── SOUL.md # Agent personality (for OpenClaw)
  184. ├── AGENTS.md # Agent instructions
  185. └── SPEC.md # Full system spec
  186. ```
  187. ---
  188. ## Contributing
  189. This is open source. PRs welcome.
  190. Ideas for contribution:
  191. - Google Ads support via a separate adapter
  192. - Creative performance dashboards
  193. - Automated A/B test analysis
  194. - Multi-account agency mode
  195. - Slack/Discord notification integrations
  196. ---
  197. MIT License. Use it, fork it, build on it.
  198. ---
  199. Built by [Matt Berman](https://twitter.com/themattberman).
  200. - 🐦 Twitter/X: [@themattberman](https://twitter.com/themattberman)
  201. - 📰 Newsletter: [Big Players](https://bigplayers.co)
  202. - 🏢 Agency: [Emerald Digital](https://emerald.digital)
  203. ---
  204. Stop babysitting Ads Manager. Let your AI copilot do the watching.
  205. Star the repo if this helps. It tells me to keep building.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.