# AdHelm

> Point your AI agent at your ad accounts. It audits, you decide.

AdHelm is a free, Apache-2.0 command-line tool that lets your AI agent connect your own ad and analytics accounts, report performance, audit them and recommend changes, entirely on your machine.

- Version: 0.1.0
- License: Apache-2.0
- Requires: Python 3.12+ on macOS, Linux, Windows
- Read-only in 0.1.0
- Source: https://github.com/jasonhowie/adhelm
- Package: https://pypi.org/project/adhelm/
- Web page: https://aptsonic.com/adhelm

## Watch

[AdHelm in 52 seconds](https://aptsonic.com/videos/adhelm-launch.mp4) (MP4, with narration). Transcript:

> Your ad accounts live in six different dashboards.
>
> What if your AI agent could read them all, right on your machine?
>
> This is AdHelm. Your agent audits, and you decide.
>
> You ask Claude Code or Codex in plain English. It finds the AdHelm commands and runs them.
>
> It checks your setup, then reads a daily report, straight from your own Google Ads account.
>
> Then it audits, and every finding shows what was read and the evidence behind it.
>
> Your history and your keys stay on your machine, with no telemetry and no hosted service.
>
> Eight providers, all free and open source.
>
> Install the command-line tool, and hand it to Claude Code or Codex.

## What it does

- **Connect:** Enroll your own provider app or key locally; check status, refresh, remove locally, and get revocation guidance.
- **Read:** Account identity, a fixed inventory and a fixed daily aggregate report.
- **Audit:** Audits state, per dimension, what was and wasn’t read, with recommendations that cite their evidence and change nothing.
- **Record:** An append-only local history you can verify, reconcile against out-of-band changes, and export as deterministic CSV and JSON.
- **Report:** Compact chat summaries by default; documents, spreadsheets or HTML reports on request.
- **Teach:** Two bundled agent skills teach the diagnose, recommend and verify loop.

## Providers

Every provider in 0.1.0 is labeled `EXPERIMENTAL`: fixture-tested, not yet piloted on a live account.

- Google Ads (`EXPERIMENTAL`)
- Meta Ads (`EXPERIMENTAL`)
- LinkedIn Ads (`EXPERIMENTAL`)
- TikTok Ads (`EXPERIMENTAL`)
- Reddit Ads (`EXPERIMENTAL`)
- OpenAI Ads (`EXPERIMENTAL`)
- GA4 (`EXPERIMENTAL`)
- GTM (`EXPERIMENTAL`)

## How it works

- **Agent-first:** You describe the goal. Your agent runs adhelm discover, calls the commands and reports back. No shell knowledge needed.
- **Local-only:** No hosted service, telemetry, account, license key or paid tier.
- **Bring your own apps:** You register your own provider applications and keep your own credentials in your OS credential store.

## Install

```sh
uv tool install adhelm
# or
pipx install adhelm

adhelm discover
```

Requires Python 3.12+. macOS, Linux and Windows.

## Not in 0.1.0

- No changes to any ad or analytics account. Write commands are listed as unreleased and refused.
- No CRM attribution (Salesforce, HubSpot).
- You obtain provider API access yourself; quotas and access tiers are the provider’s.

---

AdHelm is free and open source under the Apache-2.0 license. Built by Jason Howie (https://aptsonic.com).