Skip to content
Back to search

google-ads-assistant-local

Google Ads API Developer Assistant

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 13 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/googleads/google-ads-api-developer-assistant with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/googleads/google-ads-api-developer-assistant'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/googleads--google-ads-api-developer-assistant/badge.svg)](/listings/googleads--google-ads-api-developer-assistant)

HTML

<a href="/listings/googleads--google-ads-api-developer-assistant"><img src="/api/listings/googleads--google-ads-api-developer-assistant/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

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

1. Install Host Platform

Choose and set up your assistant environment. You can install both Antigravity and Claude Code or just one of them. Install the host platform(s) you want to use:

Antigravity CLI

* Download and install `antigravity-cli` from [https://antigravity.google/](https://antigravity.google/). * Verify your installation:

  agy --version

Claude Code

1. **Prerequisites:** Ensure [Node.js](https://nodejs.org/) (version 18 or higher) is installed on your system:

   node --version

2. **Install Claude Code CLI:** Install Claude Code globally using npm:

   npm install -g @anthropic-ai/claude-code

*(Alternatively on macOS via Homebrew: `brew install claude-code`)* 3. **Authenticate:** Run `claude` in your terminal to authenticate with your Anthropic account or configure your API key:

   claude

4. **Verify Installation:** Check that the CLI is accessible:

   claude --version

---

2. Clone the Assistant

Clone the repository to your local machine:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

---

3. Run Install Script

Run the installation script matching your platform:

* **Antigravity (Linux/macOS):** ```bash ./install.sh agy ``` *Installs plugin to `~/.gemini/config/plugins/google-ads-api-developer-assistant`.* *To include additional client libraries: `./install.sh agy --php --ruby --dotnet`.*

* **Claude Code (Linux/macOS):** ```bash ./install.sh claude ``` *Registers the repository as a local marketplace and installs the plugin into Claude Code via the `claude` CLI.* *To include additional client libraries: `./install.sh claude --php --ruby --dotnet`.*

* **Antigravity (Windows - PowerShell):** ```powershell .\install.ps1 -Type agy ``` *Installs plugin to `%USERPROFILE%\.gemini\config\plugins\google-ads-api-developer-assistant`.* *To include additional client libraries: `.\install.ps1 -Type agy -Php -Ruby -Dotnet`.*

* **Claude Code (Windows - PowerShell):** ```powershell .\install.ps1 -Type claude ``` *Registers the local marketplace and installs the plugin into Claude Code via Claude CLI.* *To include additional client libraries: `.\install.ps1 -Type claude -Php -Ruby -Dotnet`.*

---

4. **Configure Credentials:** Make sure your API credentials configuration files are in your `$HOME` directory. Each language has its own configuration file naming convention and structure. 5. **Optional: Default Customer ID:** To set a default customer ID, enter your customer ID in `config/customer_id` (e.g., `1234567890`). You can then use prompts like *"Get my campaigns"* and the Assistant will use the CID for the request. 6. **Google Ads API Version Validation:** On your first run in a session, the assistant will automatically identify the latest stable Google Ads API version and ask you to confirm it. Once confirmed, this version is cached in [api_version.txt](file:///usr/local/google/home/rwh/google-ads-api-developer-assistant/config/api_version.txt) and used for all subsequent prompts. If you need to force a version change or refresh the cache, simply delete or edit the `config/api_version.txt` file.

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.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "google-ads-assistant-local",
  3. "owner": {
  4. "name": "Google Ads API Team"
  5. },
  6. "plugins": [
  7. {
  8. "name": "google-ads-api-developer-assistant",
  9. "description": "Exposes expert Google Ads API capabilities: GAQL static analysis & live dry-runs, Protobuf object inspection, conversion diagnostics, PMax webpage filters, MCC account hierarchy retrieval, client library version discovery & sync, interactive tutorial, and Ruff-linted Python code generation.",
  10. "version": "4.0.0",
  11. "source": "./plugins/google-ads-api-developer-assistant"
  12. }
  13. ]
  14. }
README.md · README · 358 lines
  1. # Google Ads API Developer Assistant
  2. **TL;DR:** This assistant lets you interact with the Google Ads API using natural language. Ask questions, generate GAQL and code in several languages, and execute API calls directly in your terminal.
  3. ## Overview
  4. The Google Ads API Developer Assistant streamlines workflows for developers working with the Google Ads API. Use natural language prompts to:
  5. * Get answers to Google Ads API questions.
  6. * Construct Google Ads Query Language (GAQL) queries.
  7. * Generate executable code in several languages using our client libraries for context.
  8. * Retrieve and display data from the API.
  9. This assistant is powered by the **Antigravity** (v4.0.0) and **Claude Code** agent frameworks and leverages `AGENTS.md` / `CLAUDE.md` files, native slash commands, and custom **Skills** to deliver persistent context, robust safety constraints, and automated execution pipelines.
  10. ## Agentic Design & Approach
  11. The Assistant uses a structured hierarchy of instruction files, slash commands, and specialized domain tools to ensure safe, precise, and highly competent interactions with the Google Ads API across supported agent environments.
  12. ### 1. Unified Context via `AGENTS.md` & `CLAUDE.md`
  13. The master configuration files act as the system contract for the assistant:
  14. * **Version Cache Protocol**: Automatically discovers and locks the latest active API version (cached in `config/api_version.txt`).
  15. * **Version Parity Enforcement**: Verifies parity between the runtime `google-ads` Python package and local `client_libs/google-ads-python` source-of-truth definitions, issuing warnings on discrepancies.
  16. * **Code Generation Pipeline**: Passes all generated Python code through strict `ruff` linting before saving or displaying it.
  17. * **Programmatic GAQL Validation**: Evaluates queries against field metadata and compatibility boundaries.
  18. * **Safety Constraints**: Strictly prohibits running unreviewed mutate operations directly.
  19. ### 2. Domain-Specific "Skills" & Native Commands
  20. Rather than relying on generic AI completions, the assistant is empowered with specialized, test-backed tool directories under `plugins/google-ads-api-developer-assistant/skills/` and native slash commands under `plugins/google-ads-api-developer-assistant/commands/`.
  21. Key capabilities support dual invocation (natural language prompts in Antigravity or dedicated slash commands in Claude Code):
  22. * **GAQL Validation (`/validate-gaql`)**: Dry-runs queries via the API `validate_only` parameter.
  23. * **Object Inspection (`/inspect-object`)**: Inspects API resources, nested messages, or enum definitions on the fly.
  24. * **MCC Account Mapping (`/get-cids`)**: Maps client hierarchies and retrieves sub-account CIDs under manager accounts.
  25. * **Conversion Troubleshooting (`/troubleshoot-conversions`)**: Investigates conversion upload summaries and pre-validates files.
  26. * **PMax Listing Filters & URL Exclusions (`/pmax-filter`)**: Generates product partition trees and webpage URL exclusions.
  27. * **Structured Explanations (`/explain`, `/step-by-step`, `/assistant-tutorial`)**: Delivers standardized multi-part explanations, step breakdowns, and interactive tutorials.
  28. * **Environment & Library Sync (`/sync-client-libs`, `/ext-version`)**: Synchronizes client libraries and verifies active API version settings.
  29. ## Key Features
  30. * **Natural Language Q&A & Conceptual Guidance:** Ask about Google Ads API concepts, fields, and usage in plain English, or use structured explanation commands.
  31. * *Natural Language:* "What are the available campaign types?", "Tell me about reporting for Performance Max campaigns."
  32. * *Claude Code:* `/explain`, `/step-by-step`, `/assistant-tutorial`
  33. * **Natural Language to GAQL & Client Library Code:** Convert requests into executable code using the Google Ads Client Libraries.
  34. * Code is saved to `saved/code/`.
  35. * *"Show me campaigns with the most conversions last 30 days."*
  36. * *"Get all ad groups for customer '123-456-7890'."*
  37. * *"Find disapproved ads across all campaigns."*
  38. * **Validate Complex GAQL Queries:** Validate complex GAQL queries against API metadata and compatibility rules.
  39. * *Claude Code:* `/validate-gaql`
  40. * *Natural Language:*
  41. ```sql
  42. validate:
  43. SELECT
  44. campaign.id,
  45. campaign.name,
  46. campaign.status,
  47. campaign.advertising_channel_type,
  48. ad_group.id,
  49. ad_group.name,
  50. ad_group.status,
  51. ad_group_ad.ad.id,
  52. ad_group_ad.status,
  53. ad_group_ad.ad.type,
  54. ad_group_ad.policy_summary.policy_topic_entries,
  55. metrics.clicks,
  56. metrics.impressions,
  57. metrics.cost_micros,
  58. metrics.conversions,
  59. segments.date
  60. FROM ad_group_ad
  61. WHERE campaign.status = 'ENABLED'
  62. AND ad_group.status = 'ENABLED'
  63. AND ad_group_ad.status = 'ENABLED'
  64. AND segments.date DURING LAST_30_DAYS
  65. AND metrics.impressions > 100
  66. ORDER BY metrics.clicks DESC
  67. LIMIT 500
  68. ```
  69. * **Direct API Execution:** Run the generated Python code directly and view results, often formatted as tables. Execution takes place within a managed virtual environment that has the Google Ads API Client Libraries installed.
  70. * **CSV Export:** Save tabular API results to a CSV file in the `saved/csv/` directory.
  71. * *"Save results to a csv file"*
  72. * **Conversion Troubleshooting & Diagnostics:** Generate structured diagnostic reports to debug offline conversion issues.
  73. * *Claude Code:* `/troubleshoot-conversions`
  74. * *Natural Language:* *"Troubleshoot my conversions for customer '123-456-7890'."* (Reports saved to `saved/data/`).
  75. ## Supported Languages
  76. * Python
  77. * PHP
  78. * Ruby
  79. * Java
  80. * C# (.NET)
  81. Code generated by Python, PHP, and Ruby can be executed directly. Code generated by Java and C# must be compiled and executed separately. This is because of security policies. For C# code generation, use 'in dotnet' to set the context.
  82. By default, Python is strictly used for all code generation and execution across the assistant, even when other language libraries or project files are present. The assistant will only switch to generating or executing in another language if specifically requested by the user. As of v2.3.0 you can provide context from your project files using the `context_dir` flag: `./update.sh --context_dir /path/to/your/codebase`. This allows Gemini to include your application logic in its reasoning when creating responses.
  83. * Before requesting code output in a different language, tell the Assistant: `write saved code examples in <language of your application>`
  84. ## Prerequisites
  85. 1. Familiarity with Google Ads API concepts and authentication.
  86. 2. A Google Ads API developer token.
  87. 3. A configured credentials file in your home directory if using Python (`google-ads.yaml`), PHP (`google_ads_php.ini`), or Ruby (`google_ads_config.rb`).
  88. 4. Antigravity or Claude Code environment configured.
  89. 5. A local clone of each client library for the languages you want to use. `install.sh` (Linux/macOS) or `install.ps1` (Windows) can set this up for you.
  90. 6. Python >= 3.10 installed and available on your system PATH. This is required for executing the default generated Python code directly.
  91. ## Setup
  92. ### 1. Install Host Platform
  93. Choose and set up your assistant environment. You can install both Antigravity and Claude Code or just one of them. Install the host platform(s) you want to use:
  94. #### Antigravity CLI
  95. * Download and install `antigravity-cli` from [https://antigravity.google/](https://antigravity.google/).
  96. * Verify your installation:
  97. ```bash
  98. agy --version
  99. ```
  100. #### Claude Code
  101. 1. **Prerequisites:** Ensure [Node.js](https://nodejs.org/) (version 18 or higher) is installed on your system:
  102. ```bash
  103. node --version
  104. ```
  105. 2. **Install Claude Code CLI:** Install Claude Code globally using npm:
  106. ```bash
  107. npm install -g @anthropic-ai/claude-code
  108. ```
  109. *(Alternatively on macOS via Homebrew: `brew install claude-code`)*
  110. 3. **Authenticate:** Run `claude` in your terminal to authenticate with your Anthropic account or configure your API key:
  111. ```bash
  112. claude
  113. ```
  114. 4. **Verify Installation:** Check that the CLI is accessible:
  115. ```bash
  116. claude --version
  117. ```
  118. ---
  119. ### 2. Clone the Assistant
  120. Clone the repository to your local machine:
  121. ```bash
  122. git clone https://github.com/googleads/google-ads-api-developer-assistant
  123. cd google-ads-api-developer-assistant
  124. ```
  125. ---
  126. ### 3. Run Install Script
  127. Run the installation script matching your platform:
  128. * **Antigravity (Linux/macOS):**
  129. ```bash
  130. ./install.sh agy
  131. ```
  132. *Installs plugin to `~/.gemini/config/plugins/google-ads-api-developer-assistant`.*
  133. *To include additional client libraries: `./install.sh agy --php --ruby --dotnet`.*
  134. * **Claude Code (Linux/macOS):**
  135. ```bash
  136. ./install.sh claude
  137. ```
  138. *Registers the repository as a local marketplace and installs the plugin into Claude Code via the `claude` CLI.*
  139. *To include additional client libraries: `./install.sh claude --php --ruby --dotnet`.*
  140. * **Antigravity (Windows - PowerShell):**
  141. ```powershell
  142. .\install.ps1 -Type agy
  143. ```
  144. *Installs plugin to `%USERPROFILE%\.gemini\config\plugins\google-ads-api-developer-assistant`.*
  145. *To include additional client libraries: `.\install.ps1 -Type agy -Php -Ruby -Dotnet`.*
  146. * **Claude Code (Windows - PowerShell):**
  147. ```powershell
  148. .\install.ps1 -Type claude
  149. ```
  150. *Registers the local marketplace and installs the plugin into Claude Code via Claude CLI.*
  151. *To include additional client libraries: `.\install.ps1 -Type claude -Php -Ruby -Dotnet`.*
  152. ---
  153. 4. **Configure Credentials:** Make sure your API credentials configuration files are in your `$HOME` directory. Each language has its own configuration file naming convention and structure.
  154. 5. **Optional: Default Customer ID:** To set a default customer ID, enter your customer ID in `config/customer_id` (e.g., `1234567890`). You can then use prompts like *"Get my campaigns"* and the Assistant will use the CID for the request.
  155. 6. **Google Ads API Version Validation:** On your first run in a session, the assistant will automatically identify the latest stable Google Ads API version and ask you to confirm it. Once confirmed, this version is cached in [api_version.txt](file:///usr/local/google/home/rwh/google-ads-api-developer-assistant/config/api_version.txt) and used for all subsequent prompts. If you need to force a version change or refresh the cache, simply delete or edit the `config/api_version.txt` file.
  156. ## Usage
  157. 1. **Start Assistant Session:**
  158. Ask questions, generate code, and validate queries within your Antigravity terminal session or Claude Code.
  159. 2. **Ask a question:**
  160. > "What are the resource names for my enabled campaigns sorted by campaign id"
  161. 3. **Generate Code:**
  162. > "Get me the top 5 campaigns by cost last month for customer 1234567890"
  163. 4. **Execute and Save:**
  164. > "Run the code"
  165. > ... (code displayed as the result of a previous request) ...
  166. > "Save the results to csv"
  167. ## Stay in sync
  168. The Assistant includes automated synchronization tools to ensure your local client libraries, protobuf definitions, and API version metadata remain aligned with upstream releases on GitHub.
  169. ### 1. Update Check & Confirmation at Session Startup
  170. Whenever an assistant session starts in Antigravity or Claude Code, the assistant executes an automated **"Validate Before Act & Interactive Sync"** directive:
  171. * It checks both the **Assistant repository itself** and local **client libraries** (`client_libs/`) against the latest upstream GitHub releases in check-only mode (`--check_only`).
  172. * If newer assistant releases or client library updates are detected, the assistant prompts you with the available updates and asks for confirmation before downloading:
  173. > *"New updates are available on GitHub (e.g., google-ads-api-developer-assistant 4.0.0, google-ads-python 25.1.0 -> 26.0.0). Would you like to upgrade now?"*
  174. * If you confirm, it automatically synchronizes the codebases and refreshes `config/api_version.txt`. If you decline, it proceeds with your currently installed versions.
  175. ### 2. Requesting Synchronization During a Session
  176. You can check for updates or trigger synchronization at any time while in an active session:
  177. * **Natural Language Prompts (Antigravity & Claude Code):**
  178. * *"Sync my client libraries"*
  179. * *"Check for Google Ads client library updates"*
  180. * *"Update the Python client library to the latest release"*
  181. * **Dedicated Slash Command (Claude Code):**
  182. * Run `/sync-client-libs` to inspect and synchronize all local client libraries.
  183. * Target a specific library: `/sync-client-libs python` or `/sync-client-libs dotnet`.
  184. * **Verify Active Version:**
  185. * Claude Code: `/ext-version`
  186. * Natural Language: *"What is the active Google Ads API version?"*
  187. ### 3. Manual Terminal Updates
  188. To update the repository, assistant plugin, and all configured client libraries outside an active session:
  189. * **Linux/macOS:**
  190. ```bash
  191. ./update.sh agy --all # Update Antigravity plugin and all client libraries
  192. ./update.sh claude --all # Update Claude Code plugin and all client libraries
  193. ```
  194. * **Windows (PowerShell):**
  195. ```powershell
  196. .\update.ps1 -Type agy -All
  197. .\update.ps1 -Type claude -All
  198. ```
  199. ### 4. Client Library & Runtime Version Parity
  200. The Assistant relies on local client library sources (`client_libs/google-ads-python`) as the primary **source of truth** for Protobuf schemas, resource definitions, and enum descriptors, while executing queries and generated code through the installed `google-ads` Python package in your environment.
  201. To prevent silent schema discrepancies, missing fields, or descriptor errors:
  202. * **Automated Parity Checks:** Tool scripts (such as `inspect_object.py`) automatically compare the installed environment package version (`importlib.metadata.version('google-ads')`) against the local `client_libs/google-ads-python` version metadata (`pyproject.toml` / `ChangeLog`).
  203. * **Warning Directives:** If a version mismatch is detected, the Assistant and inspection tools output an explicit warning banner:
  204. ```text
  205. WARNING: Installed google-ads package version (<installed_version>) does not match client_libs/google-ads-python version (<client_libs_version>) used for protobuf inspection. Schema inspection or API calls may encounter field discrepancies.
  206. ```
  207. * **Resolving Mismatches:**
  208. * Synchronize client libraries to latest: `/sync-client-libs` (or prompt *"Sync client libraries"*).
  209. * Upgrade the runtime Python package: `pip install --upgrade google-ads` (or within virtualenv: `source .venv/bin/activate && pip install --upgrade google-ads`).
  210. * Perform a complete update: `./update.sh agy --all` or `./update.sh claude --all`.
  211. ## Directory Structure
  212. * `plugins/google-ads-api-developer-assistant/`: Source directory for the assistant plugin.
  213. * `plugins/google-ads-api-developer-assistant/commands/`: Native slash commands for Claude Code.
  214. * `plugins/google-ads-api-developer-assistant/skills/`: Assistant skills (GAQL analyzer, proto inspect, etc.).
  215. * `plugins/google-ads-api-developer-assistant/rules/`: Agent behavioral rules and protocols.
  216. * `plugins/google-ads-api-developer-assistant/sidecars/`: Background sidecar microservices.
  217. * `plugins/google-ads-api-developer-assistant/client_libs/`: Cloned client libraries.
  218. * `plugins/google-ads-api-developer-assistant/mcp_config.json`: Model Context Protocol configuration.
  219. * `config/`: Configuration files (e.g. `api_version.txt`, `customer_id`).
  220. ## Plugin Architecture
  221. To learn more about how Antigravity and Claude define plugins, see the [Antigravity plugin specification](https://antigravity.google/docs/cli/plugins/) and the [Claude plugin specification](https://github.com/anthropics/knowledge-work-plugins).
  222. ## Mutate Operations
  223. The Assistant is designed to generate code for mutate operations (e.g., creating campaigns, adding users) but will **not** execute them. This execution policy ensures you have full control over any changes to your Google Ads account. You must review the generated code for accuracy and execute it manually outside of the Assistant.
  224. ## Known Quirks
  225. * The underlying model may have been trained on an older API version. It may occasionally generate code with deprecated fields. Execution errors often provide feedback that allows the assistant to self-correct on the next attempt, using the context from the client libraries. To avoid these errors, we always search for the latest version of the API when initializing the session and ask you to verify the version.
  226. ## Maintenance
  227. We will periodically release updates to the assistant and client libraries.
  228. To update your repository, plugin installation, and client libraries:
  229. * **Linux/macOS:**
  230. ```bash
  231. ./update.sh agy # Update Antigravity plugin
  232. ./update.sh claude # Update Claude Code plugin
  233. ```
  234. To add or update specific client libraries:
  235. ```bash
  236. ./update.sh agy --java --dotnet
  237. ```
  238. * **Windows:**
  239. ```powershell
  240. .\update.ps1 -Type agy
  241. .\update.ps1 -Type claude
  242. ```
  243. To add or update specific client libraries:
  244. ```powershell
  245. .\update.ps1 -Type agy -Java -Dotnet
  246. ```
  247. ## Uninstallation
  248. To remove the Google Ads API Developer Assistant plugin, use the native uninstallation mechanism for your platform:
  249. ### Antigravity
  250. Delete the installed plugin directory:
  251. * **Linux/macOS:**
  252. ```bash
  253. rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant
  254. ```
  255. * **Windows (PowerShell):**
  256. ```powershell
  257. Remove-Item -Recurse -Force "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"
  258. ```
  259. Restart your Antigravity / agy host session to complete the uninstallation.
  260. ### Claude Code
  261. * **Within an active Claude Code session:**
  262. ```text
  263. /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local
  264. ```
  265. * **Or from your terminal:**
  266. ```bash
  267. claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local
  268. ```
  269. *(Optional)* To remove the local marketplace registration as well:
  270. * **Within Claude Code:** `/plugin marketplace remove google-ads-assistant-local`
  271. * **From terminal:** `claude plugin marketplace remove google-ads-assistant-local`
  272. ## Contributing
  273. Please see `CONTRIBUTING.md` for guidelines on reporting bugs, suggesting features, and submitting pull requests.
  274. ## Support
  275. Use the GitHub Issues tab for bug reports, feature requests, and support questions.
  276. ## License
  277. Apache License 2.0. See the `LICENSE` file.

Ratings and comments

Sign in to rate this skill.

Sign in

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