ai tag debugger

English | Türkçe

An open-source AI agent that QA-tests your website's analytics and ad tracking.

An AI model drives a real browser through your key journeys (product → cart → checkout, lead forms) like a real visitor. While it browses, ai-tag-debugger records every tracking hit (GA4, Google Ads, Meta Pixel, TikTok and about a dozen more platforms) and every dataLayer push. It then checks them against your measurement plan and Consent Mode setup and writes a plain-language report of what broke and how to fix it, in English or Turkish.

Use it in two ways:

• From your terminal or CI, with your own API key for Anthropic (Claude), OpenAI, Google Gemini, or any OpenAI-compatible API (Kimi, GLM, DeepSeek, OpenRouter, a local Ollama and more).
• From your AI chat app (Claude, ChatGPT, Gemini and other apps that support MCP). The app's own model drives the audit, so you don't need a separate API key.

Built by Analitik İşler. MIT licensed.

▶ checkout (mobile)

Accept cookies Open the first product Add to cart Open the cart Go to checkout … Place the order ✓ All scripted steps completed. · 20 tracking hits captured

2 broken · 1 risk · 1 warning · 4 ok Report: reports/demo/localhost/runs/2026-10-16_0800/report.html

Why

Tracking breaks silently. A redesign renames a button, a new template forgets a field, a consent banner update lets pixels fire too early. Nobody gets an alert. You find out weeks later, after ad platforms have optimized on bad conversions.

Manual tag QA catches this, but it's tedious, so it rarely happens after every release. ai-tag-debugger makes it a command you can run in CI.

What it checks

Platforms: GA4 (including server-side GTM endpoints and Google tag gateway paths on the site's own domain; hits to a server container are marked server-side, and Stape and Elevar requests are recognised), Google Ads conversions, Meta Pixel, TikTok Pixel, basic X Pixel events, LinkedIn Insight Tag, Microsoft Advertising UET, Criteo OneTag, and Pinterest, Snapchat and Klaviyo events. Adobe Analytics, Matomo and Piwik PRO events are read too (page views, links, goals, site search and ecommerce orders), and Microsoft Clarity and Hotjar tag loads name the project or site id.

When GA4 hits go to a server container on another host, or its loader is served from one, the report adds an info finding: the events it forwards to ad platforms never pass through the browser, so they can't be seen here.

With a gtm_container export, each broken event also names the GTM tag that sends it and the trigger it fires on, or says that no tag sends it. Each tag then says whether its trigger fired in that journey and, when it did not, why: the tag is paused, no dataLayer push carried the trigger's event, a trigger condition failed (with the value the push had, read from the cumulative dataLayer the way GTM's Data Layer Variables read it), an exception trigger blocked it, or the consent it needs was denied when the event fired. When everything fired and the hit is still wrong, it says so, pointing at the tag's own setup. Click, form, visibility and timer triggers are evaluated by GTM in the page, so they are reported as not evaluable unless their gtm.click-style event reached the dataLayer. All of this is evaluated from the captured dataLayer, with no AI model.

Choose the platforms to check

By default an audit checks GA4, Google Ads, Meta and TikTok, and also any other platform the site turns out to use. That platform is checked from its first request, with no setting needed. Choosing platforms turns this detection off. Pick a fixed list with --platforms ga4,meta,x, "providers" in the config, or providers on the MCP start_audit and run_audit tools. You can choose from ga4, google_ads, meta, tiktok, x, linkedin, microsoft_ads, pinterest, snapchat, criteo, klaviyo, adobe, matomo, piwik_pro, clarity, hotjar, doubleclick and adsense. Events are parsed for GA4, Google Ads, Meta, TikTok, X, LinkedIn, Microsoft Ads, Pinterest, Snapchat, Criteo, Klaviyo, Adobe Analytics, Matomo and Piwik PRO. Clarity and Hotjar show their tag loads, and the others show their network requests. --providers still works as the old name of --platforms for one more minor version and prints a note.

Requests to platforms you didn't choose are still answered locally, so they never reach those accounts either. They are left out of the timeline, the CSV and the checks, and only counted: the report lists them with their request counts (for example "61 out-of-scope requests were skipped: Microsoft Clarity, DoubleClick"), and each step says how many it skipped. Without --platforms, any platform your measurement plan names or the site sends to is added to the default list. Planned events for platforms you did leave out are listed in one info finding instead of being reported as missing. Tag manager and consent platform requests are always shown.

Consent scenarios

Each audit also opens the start page once per consent choice, each time in a fresh browser and like an ad click (with the same test campaign parameters as the journeys, unless campaign_checks is false): no choice and on to the next page, accept all, reject all and analytics only. The choice goes through the consent platform's own API (OneTrust, Cookiebot, Usercentrics, Didomi or Efilli) or, for CookieYes, its named buttons and switches, or else by clicking the banner's buttons. The report then shows how many hits each tag sent after each choice. Analytics only works with OneTrust (it turns on the group OneTrust's Consent Mode setting gives analytics_storage), Cookiebot and CookieYes, and with Efilli when its own Consent Mode integration is on (it turns on the category Efilli maps analytics_storage to); with other platforms that column says "Not supported here". A tag that sends after reject all, or on the next page when the visitor made no choice (browsing on is no consent under the GDPR or KVKK), is flagged, except cookieless Consent Mode pings. An advertising tag that sends after analytics only is flagged unless it was sent with ad storage denied. The table is at the top of the Journeys tab and above the findings in report.md. It is skipped when the page shows no banner the tool can answer, and when a saved site is replayed.

Under it, the Consent matrix puts the choices side by side, from the page each one leads to: the first Google hit and the consent it carries, whether the campaign parameters reached it, whether the GA4 client id the visitor had before choosing was kept, whether _gcl_aw holds the landing gclid, the cookies set, how long after the page started each tag was called, and the Google tag's own consent. What should not happen with a choice is marked: tracking cookies before a choice, without one or after reject all, a client id that changes on accept, and a UTM parameter lost from the first hit. The same matrix is in report.md, and the consent_matrix MCP tool runs it on its own.

The Consent section also names the consent platform the site runs. For Efilli it says when the site's bundle was compiled, which language's setup is in force, its categories, whether Efilli's own Consent Mode integration is on and the category each signal maps to (and, when it is off, that the signals come from somewhere else, such as a GTM template), and whether auto-blocking and IAB TCF are on. For CookieYes it gives the law its banner follows, its categories, how it maps them to Consent Mode (the same on every site: advertisement to ad_storage, ad_user_data and ad_personalization, analytics to analytics_storage, functional to functionality_storage and personalization_storage, necessary to security_storage), how many providers it holds back, and when its site script last changed. For OneTrust: its version, the consent model and region it applied to the visit, its groups, whether its Consent Mode setting is on and which group grants each signal, ads data redaction, IAB TCF, and when the site last published its setup. For Cookiebot: its version, consent model and region, its fixed mapping (marketing to the three ad signals, statistics to analytics_storage, preferences to functionality_storage and personalization_storage), whether its Consent Mode integration is on, ads data redaction, auto-blocking, IAB TCF, and when its setup was last published.