civic-gads

civic-gads — Google Ads API Developer Assistant for Claude Code

A Claude Code plugin that turns your terminal into a Google Ads API expert. Ask questions in natural language, generate validated GAQL and Python (or PHP / Ruby / Java / .NET) code against the official client libraries, and execute read-only API calls — all with strict guardrails.

This is a Civic-internal port of googleads/google-ads-api-developer-assistant from a Gemini CLI extension to a Claude Code plugin. See NOTICE for the attribution and a list of port changes.

What it can do

• Natural-language Q&A about API concepts, fields, and usage.
• GAQL generation with a 4-step validation pipeline: schema discovery → compatibility check → static analysis → runtime dry-run via validate_only=True.
• Code generation in Python (default), PHP, Ruby, Java, or C#. Python / PHP / Ruby code can be executed directly from the chat; Java and C# are generated for you to compile separately.
• Direct API execution inside a managed .venv/ so the host system stays clean.
• CSV export of tabular results to saved/csv/.
• Conversion troubleshooting via /conversions_support_package, which produces a single-file diagnostic bundle for gTech support.
• GAQL validation on demand — paste any query after validate: and the agent will run it against the strict rule set.

Hard guardrails (preserved verbatim from upstream)

• Read-only. No mutate, create, update, or delete API calls.
• No OR in GAQL. The agent uses IN or executes multiple queries.
• No FROM in metadata queries. GoogleAdsFieldService queries are enforced bare.
• Mandatory ruff lint on every generated Python script before write/exec.
• Mandatory validate_only=True dry-run on every GAQL query before exec.
• No client library mutations. client_libs/ is read-only context.
• No secrets in chat. Developer tokens, OAuth secrets, and PII are never printed or persisted.
• No version persistence. The confirmed Google Ads API version is per-session and never written to Claude Code's auto-memory.

Supported languages

Language	Generation	Direct execution
Python (default)	✓	✓
PHP	✓	✓
Ruby	✓	✓
Java	✓	(compile separately)
C# (.NET)	✓	(compile separately)

To generate code in a non-default language, tell the agent: write saved code examples in <language>. For C#, use in dotnet to set the context.

Prerequisites

1. Familiarity with Google Ads API concepts and authentication.
2. A Google Ads API developer token.
3. A configured credentials file in your home directory:
   • Python: ~/google-ads.yaml
   • PHP: ~/google_ads_php.ini
   • Ruby: ~/google_ads_config.rb
   • Java: ~/ads.properties
4. Claude Code installed.
5. Python ≥ 3.10 on your PATH (used by the SessionStart hook to provision .venv/).
6. git. The Bash installer drops the upstream jq dependency.

For service-account / impersonation setups, see SERVICE_ACCOUNT.md.

Setup

Option A — Install as a Claude Code plugin (recommended)

The repo is also a single-plugin Claude Code marketplace. From inside any Claude Code session:

/plugin marketplace add civicteam/civic-gads
/plugin install civic-gads@civic-gads

Then run ./install.sh from the cloned plugin directory once to fetch the Google Ads client libraries (the plugin install only fetches the plugin sources; the client libs are large and stay opt-in).

Option B — Clone and run directly

git clone https://github.com/civicteam/civic-gads.git
cd civic-gads/plugins/civic-gads
./install.sh                     # Python only (default)
./install.sh --php --ruby        # add other languages as needed
claude                           # open this directory in Claude Code

The first time you start a session, the SessionStart hook will:

1. Create ./.venv/ and install google-ads + ruff into it.
2. Copy your credentials from ~/google-ads.yaml (or a fallback) into ./config/google-ads.yaml, appending the plugin version for telemetry.
3. Inject the deterministic venv path and GOOGLE_ADS_CONFIGURATION_FILE_PATH into the session via Claude Code's additionalContext channel.

When the session ends, the SessionEnd hook removes ./.venv/ and clears ./config/, so credentials never linger on disk.

Try it

> What are the available campaign types?
> Show me campaigns with the most conversions in the last 30 days.
> Get all ad groups for customer '123-456-7890'.
> Find disapproved ads across all campaigns.
> Save results to a csv file
> Troubleshoot my conversions for customer '123-456-7890'.

Slash commands: