Budget Guardian

Budget Guardian

A spend tripwire for your Google Ads MCC. Scans every enabled account in your MCC every 2 hours. If month-to-date spend crosses 100% or 120% of the monthly budget you set, it pings Slack. Alert-only — never pauses campaigns.

Why this exists

Two threats with the same shape — a spend spike nobody noticed until the damage was done.

The first is fat-fingering: a wrong formula or stale value in a budget sheet quietly pushing the wrong number across multiple accounts. The second is the industry-wide trend of hijacked MCCs and malicious spend — unauthorized PMax campaigns at huge daily budgets, drained accounts, agency-level changes nobody approved.

Daily checks miss the first 23 hours of either one. A 2-hour cron with per-threshold dedupe gets detection to ~2 hours, with one alert per account per threshold per month so Slack doesn't get spammed.

Architecture

GitHub Actions (every 2 hours)
        |
        v
  Read budget sheet     ----->  Google Sheets API
        |                       (your per-account monthly budgets)
        v
  For each account:
    Query MTD spend     ----->  Google Ads API v23
        |                       (segments.date DURING THIS_MONTH)
        v
    Compare to budget
        |
        v
    Cross threshold?    ----->  Slack webhook
        |                       (100% warning / 120% critical)
        v
    Record alert        ----->  Google Sheets API
                                (state tab — dedupe within month)

When Claude should invoke this skill

• User asks to "set up budget guardian", "install spend alerts", or "deploy budget guardian"
• User asks how to monitor MCC spend or catch hijacked accounts
• User asks about per-account budget alerting via Slack
• User describes an MCC hijack scenario, runaway PMax, or fat-fingered budget concerns

How Claude helps the user deploy this

1. Confirm prerequisites are in place (Google Ads API access, Google Sheets OAuth token, Slack workspace, GitHub repo for the cron)
2. Walk through README.md setup steps — copying files, setting GitHub secrets, creating the budget sheet
3. Run setup_tabs.py once to bootstrap the Guardian Config and Guardian State tabs
4. Trigger a manual test run via workflow_dispatch to confirm Slack receives the test message
5. Set the kill switch to ENABLED in the sheet
6. Confirm the 2-hour cron is firing in the Actions tab

Files in this skill

| File | Purpose | |------|---------| | SKILL.md | This file | | README.md | Full setup guide with step-by-step deployment | | requirements.txt | Python dependencies | | sheet-template.md | Google Sheet column structure | | .github/workflows/budget-guardian.yml | GitHub Actions cron config (every 2 hours) | | workflows/budget_guardian/main.py | Entry point — orchestrates checks | | workflows/budget_guardian/ads_api.py | Google Ads API client (MCC scan + MTD spend) | | workflows/budget_guardian/sheets_io.py | Sheet reads/writes for budgets + state | | workflows/budget_guardian/slack.py | Slack alert formatting | | workflows/budget_guardian/setup_tabs.py | One-time bootstrap of Config + State tabs | | workflows/_shared/google_auth.py | Google Sheets OAuth helper | | workflows/_shared/google_ads_auth.py | Google Ads API OAuth helper | | workflows/_shared/sheets_retry.py | Retry helper for transient Sheets errors |

Configuration

All identity-bearing values are loaded from environment variables. Nothing is hardcoded.

| Env var | Purpose | |---------|---------| | GUARDIAN_SHEET_ID | Google Sheet ID where budgets and state live | | GUARDIAN_BUDGET_TAB | Tab name with per-account budgets (default: Budgets) | | GOOGLE_TOKEN_PATH | Path to your Google Sheets OAuth user token JSON | | GOOGLE_ADS_YAML_PATH | Path to your Google Ads API YAML config | | SLACK_WEBHOOK_URL | Incoming webhook URL for the channel that should receive alerts | | SLACK_USER_MENTION | Optional — Slack user/group to @-mention on alerts (e.g. ``) |

Tested against

• Google Ads API v23
• Python 3.12
• GitHub Actions (Ubuntu)
• Slack incoming webhooks (Block Kit)
• Google Sheets API v4 with OAuth user credentials
• Portfolios of 20-90 accounts

What this skill deliberately does NOT do

• Does not pause campaigns. Alert-only by design. Auto-pause has too many failure modes for a public-default skill.
• Does not modify Google Ads. Read-only access is sufficient.
• Does not need Anthropic credentials. No LLM call in the loop — pure threshold math.
• Does not require a brain. Runs standalone on GitHub Actions; the SKILL.md just helps Claude help you deploy it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fourteenwm
• Source: fourteenwm/ppc-ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.