> [!NOTE]
> **Note:** This tool is an open-source project and not an official Google product.

The Google Ads API Developer Assistant brings deep Google Ads API domain expertise directly
into your AI coding environment. Use natural language prompts and built-in
slash commands to construct queries, generate client library code, execute
read-only API calls, stream ad hoc reports, and troubleshoot integrations.

The Assistant is built for the **Google Antigravity** and **Claude Code** agent
frameworks (v4.0.0) as a modular plugin. It uses `AGENTS.md` and `CLAUDE.md`
contracts, built-in slash commands, and specialized domain skills to maintain
persistent context, robust safety boundaries, and automated validation
pipelines. See [What is the Google Ads API Developer Assistant?](https://developers.google.com/google-ads/api/docs/developer-toolkit/what-is-developer-assistant) for an
overview of its architecture and design.

> [!CAUTION]
> **Important:** Version 4.0.0 is a major release built on a modern global plugin architecture and is not backward compatible with previous project-bound releases. Follow the installation steps in this guide to set up the plugin.

## Prerequisites

Before you begin, make sure you have the following:

1. **Google Ads API access:**

   - A [Google Cloud project](https://developers.google.com/google-ads/api/docs/oauth/cloud-project) with Explorer access, Basic access, or Standard access levels. To check your project's access levels or apply for an appropriate access level, see [API access levels](https://developers.google.com/google-ads/api/docs/api-policy/access-levels#access-levels).
   - A [Google Ads configuration file](https://developers.google.com/google-ads/api/docs/client-libs#configuration) configured with your OAuth 2.0 credentials and customer ID, located in your home directory. See the [client library configuration guide](https://developers.google.com/google-ads/api/docs/client-libs/python/configuration).
   - Familiarity with Google Ads API concepts and authentication.
2. **Software:**

   - [Python](https://www.python.org/downloads/) 3.10 or newer installed and on your system PATH. Python is used for executing generated code and running local validation sidecars.
   - Host Agent Platform:
     - [Google Antigravity command-line tool](https://antigravity.google/) (`agy`), or
     - [Claude Code command-line tool](https://claude.ai/code) (`claude` with Node.js 18+).
   - [Git](https://git-scm.com/) installed on your system PATH.

## Get started

Follow these steps to clone the repository, run the platform-specific
installation script, configure your credentials, and activate the plugin.

### 1. Clone the repository

Clone the repository to your local machine and navigate to the project
directory:

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

### 2. Run the installation script

Run the installation script for your target platform. By default, the Python
client library is included. You can optionally include additional client
libraries (`--php`, `--ruby`, `--java`, `--dotnet`, or `--all`).

### Antigravity

**Linux / macOS:**

    ./install.sh agy
    # Or include additional client libraries:
    ./install.sh agy --java --dotnet

**Windows (PowerShell):**

    .\install.ps1 -Type agy
    # Or include additional client libraries:
    .\install.ps1 -Type agy -Java -Dotnet

### Claude Code

**Linux / macOS:**

    ./install.sh claude
    # Or include additional client libraries:
    ./install.sh claude --php --dotnet

**Windows (PowerShell):**

    .\install.ps1 -Type claude
    # Or include additional client libraries:
    .\install.ps1 -Type claude -Php -Dotnet

### 3. Configure credentials

Make sure your API configuration file (for example, `google-ads.yaml`,
`google_ads_php.ini`, or `google_ads_config.rb`) is placed in your `$HOME`
directory.

*(Optional)* To configure a default customer ID, enter your customer ID number
directly into `config/customer_id.txt` (for example, `1234567890`). You can also
inspect or pin your active API version in `config/api_version.txt`.

### 4. Activate the plugin

- **Antigravity:** Restart your Antigravity / `agy` host session to load the plugin.
- **Claude Code:** In an active Claude Code session, run `/reload-plugins` or restart `claude`.

### 5. Interact with the Assistant

You can interact with the Assistant using natural language prompts or dedicated
slash commands directly in your terminal.

## Key features

- **Natural language Q\&A and conceptual guidance:** Ask questions about
  Google Ads API features, architectural rules, best practices, or specific
  resources. The Assistant grounds responses in official API definitions
  rather than relying solely on general LLM training.

  - *"What are the available campaign types?"*
  - *"How do I filter by date in GAQL?"*
  - *"Explain the difference between click_view and impression_view."*
  - *"What is a shared set and how do I use it?"*
  - *Claude Code slash commands:* `/explain`, `/step-by-step`, `/assistant-tutorial`
- **Grounded client library code generation:** Generate tested, idiomatic code
  using official Google Ads client libraries (Python, Java, PHP, .NET, and
  Ruby).

  - *"Show me campaigns with the most conversions in the last 30 days."*
  - *"Get all enabled ad group names for customer 123-456-7890."*
  - *"Write code to create a Performance Max campaign."* Generated code is saved in the `saved/code/` directory.
- **Programmatic GAQL query validation:** Automatically dry-run and validate
  complex queries against API metadata, field compatibility, zero-impression
  rules, and date segmentation before execution.

  - *Claude Code:* `/validate-gaql`
  - *Natural Language:* `validate: SELECT campaign.id FROM campaign`
- **Object and Protobuf schema inspection:** Dynamically inspect resource
  structures, nested fields, data types, and enum values for any active
  API version without remote metadata overhead.

  - *Claude Code:* `/inspect-object <resource_or_enum>`
  - *Natural Language:* *"Inspect campaign resource"*
- **Ad hoc live reporting and CSV export:** Ask for performance data in plain
  English. The Assistant constructs, validates, and runs GAQL queries directly
  against your account, streaming live formatted tables into the terminal.

  - *"Show top 5 keywords by cost last month for customer 123-456-7890."*
  - *"Save the results as a CSV file."* (Exports to `saved/csv/`).
- **Direct API execution and mutate safety:** Execute generated read-only
  scripts directly within a managed virtual environment.

  - Tell the Assistant: *"Run the code"* or *"Execute the script"*.
  - **Mutate Safety:** For safety, mutating operations (create, update, delete) are generated to `saved/code/` but **never** executed directly by the assistant. Review and execute them manually outside the assistant.
- **Advanced diagnostics and conversion troubleshooting:** Investigate
  offline conversion upload failures, pre-validate upload files, and generate
  detailed diagnostic reports.

  - *Claude Code:* `/troubleshoot-conversions`
  - *Natural Language:* *"Troubleshoot conversions for customer 123-456-7890."* (Reports saved to `saved/data/`).
- **Manager account hierarchy mapping:** Retrieve sub-account customer IDs and
  map account hierarchies under a manager account.

  - *Claude Code:* `/get-cids <manager_cid>`
  - *Natural Language:* *"Get all client customer IDs under manager 123-456-7890"*
- **Performance Max listing filters and exclusions:** Generate product
  partition trees and webpage URL exclusions for asset groups.

  - *Claude Code:* `/pmax-filter`
  - *Natural Language:* *"Create webpage exclusion filters for my PMax campaign"*
- **Additional codebase context:** Register your application logic and custom
  architecture into the Assistant's reasoning.

  - **Linux / macOS:**

        ./update.sh agy --context_dir /path/to/your/codebase
        # Or for Claude Code:
        ./update.sh claude --context_dir /path/to/your/codebase

  - **Windows (PowerShell):**

        .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

## Claude Code slash commands reference

When using Claude Code, the following built-in slash commands are available.
In Google Antigravity, invoke these same capabilities using natural language
prompts or skill tool names like `validate_gaql` and `inspect_object`, as
described in [Key features](https://developers.google.com/google-ads/api/docs/developer-toolkit/ai-assistant#key-features):

| Slash command | Purpose | Example |
|---|---|---|
| `/validate-gaql` | Validates GAQL syntax, compatibility, and rules. | `/validate-gaql` |
| `/inspect-object` | Inspects Protobuf fields, types, and enums. | `/inspect-object Campaign` |
| `/get-cids` | Resolves manager account hierarchies and client CIDs. | `/get-cids 1234567890` |
| `/troubleshoot-conversions` | Runs offline conversion upload diagnostics. | `/troubleshoot-conversions` |
| `/pmax-filter` | Generates PMax listing filters and exclusions. | `/pmax-filter` |
| `/explain` | Delivers a 4-part structured explanation. | `/explain shared set` |
| `/step-by-step` | Formulates a multi-phase task execution plan. | `/step-by-step upload conversions` |
| `/assistant-tutorial` | Runs an interactive 11-step walkthrough. | `/assistant-tutorial` |

## Maintenance and updates

To update the repository, plugin installation, and client libraries:

### Antigravity

**Linux / macOS:**

    ./update.sh agy          # Update Antigravity plugin
    ./update.sh agy --all    # Include all client libraries

**Windows (PowerShell):**

    .\update.ps1 -Type agy
    .\update.ps1 -Type agy -All

### Claude Code

**Linux / macOS:**

    ./update.sh claude       # Update Claude Code plugin
    ./update.sh claude --all # Include all client libraries

**Windows (PowerShell):**

    .\update.ps1 -Type claude
    .\update.ps1 -Type claude -All

## Uninstallation

To uninstall the assistant plugin:

### Antigravity

**Linux / macOS:**

    rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

**Windows (PowerShell):**

    Remove-Item -Recurse -Force `
      "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Then restart your Antigravity host session.

### Claude Code

In an active Claude Code session:

    /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Or from your terminal:

    claude plugin uninstall \
      google-ads-api-developer-assistant@google-ads-assistant-local

*(Optional)* Remove the local marketplace registry:

    claude plugin marketplace remove google-ads-assistant-local

## Community and support

- **GitHub issues:** Report bugs, suggest features, or ask for help on the [Issues tab](https://github.com/googleads/google-ads-api-developer-assistant/issues) in the repository.
- **Discord:** Join the discussion in the `#ads-api-ai-tools` channel on the [Google Advertising and Measurement Community Discord
  server](https://goo.gle/google-ads-discord).
- **Feedback:** Share your feedback through this [survey form](https://goo.gle/feedback-googleadsapiassistant-li).

## Contribution guidelines

Contributions are welcome! See the `CONTRIBUTING.md` file in the
[GitHub repository](https://github.com/googleads/google-ads-api-developer-assistant) for guidelines.

## Next steps

- [Install Google Ads API agent skills](https://developers.google.com/google-ads/api/docs/developer-toolkit/agent-skills)
- [Connect your AI client to the Google Ads MCP server](https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server)
- [Learn how the Google Ads API Developer Assistant works](https://developers.google.com/google-ads/api/docs/developer-toolkit/what-is-developer-assistant)