Tracking Agent docs
Tracking Agent docs: what it does and how it works
The Datalyze Tracking Agent keeps your tracking plan, your code and your analytics data in step, with a PR check and an audit. It runs on your own GitHub runner with your own AI model, and a person approves every tracking change before it merges. These docs cover setup, the method it follows, every status and command, and the files it keeps in your repo.
What does the Tracking Agent do?
It has two features. The PR check works out what each pull request does to your tracking: tracking the change needs and doesn't have, existing events it breaks, events that are now dead, and user properties it affects. The audit compares your tracking plan, what your code fires and what your analytics tool actually received.
- Pull requestA developer changes the product.
- PR checkThe agent proposes tracking changes. A reviewer approves, the agent implements and verifies, a reviewer signs off.
- RegistryThe approved plan merges with the code, as YAML in
analytics/registry/. - Google SheetRebuilt from the registry after every merge, for people who don't read YAML.
- AuditChecks the plan and the code against what your analytics tool received.
Most pull requests need no tracking change. Those pass with a one-line reason, and when a script can tell (only docs, styles or assets changed), no model runs at all.
Where does the Tracking Agent run?
On your GitHub Actions runner, or on a laptop. Model calls go to your provider with your key, analytics queries go to your tool with your access, and the only call to Datalyze sends your workspace key to check the licence. Your data and keys has the full list.
The check is a required status check on your default branch, so GitHub holds the merge until a person has approved the proposal and signed off the verified result.
How well does the Tracking Agent catch tracking problems?
We test the PR check on 13 seeded repos with 11 planted problems, the ones we find most often in client audits: an event renamed in place, a call that now fires at the wrong moment, a missing entry_point, a dead event, a stale user property, set instead of set_once, personal data in a property, and an action with no outcome event. Three of the repos are clean and must pass untouched.
| Run (20 Oct 2026) | Planted problems caught | False alarms | Clean pull requests untouched | Model cost |
|---|---|---|---|---|
| 06:48 | 11 of 11 | 0 | 3 of 3 | $3.35 |
| 07:34 | 10 of 11 | 0 | 3 of 3 | $3.34 |
| 07:41, after a method fix | 11 of 11 | 1 | 3 of 3 | $3.32 |
| 09:17, after an independent review's fixes | 11 of 11 | 0 | 3 of 3 | $3.65 |
The one miss was a method gap: the agent saw that a sign-up event now fired before the sign-up request, called it a code bug rather than a tracking change, and dropped it. Now a call that a pull request breaks is always proposed as a fix.
The agent also checks this site's own repo. Two real pull requests went through the whole flow, from proposal to sign-off, for about $3.20 and $1.10 of model spend.
What does the Tracking Agent support today?
| Area | Available now | Not available yet |
|---|---|---|
| Languages | TypeScript and JavaScript for web apps, Node servers and React Native; Swift, Kotlin and Dart for mobile apps | Python, Ruby, Go and Java beyond pattern scanning |
| Analytics data | Recipes for Mixpanel, PostHog and Amplitude; SQL on BigQuery, Snowflake or ClickHouse; any tool through your AI's MCP connection on a laptop run | Other tools' APIs without a recipe |
| Typed tracker adapter | Mixpanel, PostHog, Amplitude, Segment, RudderStack and GA4, in the browser, on the server and in Swift, Kotlin and Dart apps | A custom HTTP endpoint |
| Models | Anthropic, OpenAI, Google Gemini, AWS Bedrock, Google Vertex, your gateway, a local Claude Code login | A local Codex login |
| Verification | Scripts, your own checks, generated tests (on web and mobile), an independent verifier, and an optional live test in a browser | Live tests on a mobile emulator or simulator (not planned: mobile is checked by unit tests) |
| After merge | The Google Sheet rebuilt from the registry on your default branch, and a post-release watch on recently merged changes | Registry statuses updated automatically (planned to implemented) |
If you don't have a tracking plan yet, the playbook chapter on creating a tracking plan is the place to start. For a one-off clean-up of tracking that has drifted, our analytics audit is faster than installing a check.
Which docs page answers my question?
| Page | What it answers |
|---|---|
| Setup | Browser setup step by step, the command-line route, and what the setup pull request adds. |
| Your data and keys | What stays with you, what Datalyze sees, and where each key and token lives. |
| Concepts | The registry, typed tracker, proposals, conventions, decisions, baseline and statuses, each defined. |
| The tracking-plan method | The four design rules, what to track and ignore, the event budget, and how breaking changes are handled. |
| The PR check | Every status and what to do about it, new pushes, skips, drafts, cost, and what happens when the licence lapses. |
| Reviewing | The review inbox, editing and adding items, rules, sign-off, and the GitHub-only comment commands. |
| Verification | The verification layers, the fix loop, web versus mobile, and the optional live test in a real browser. |
| The audit | Scopes, how to run it, what each bucket means, reading the report, the post-release watch, and how findings get fixed. |
| User properties and identity | How user properties, super properties, groups and identify and reset calls are planned, checked and audited. |
| Connecting analytics | The four ways the agent reads analytics data, the Mixpanel, PostHog and Amplitude recipes, SQL on BigQuery, Snowflake or ClickHouse, what a data snapshot holds, and what it never holds. |
| Mobile apps | Swift, Kotlin and Dart trackers and adapters, the mobile scanner, generated unit tests, and the post-release watch by app version. |
| Models | Providers, organisation secrets, cloud identity, gateways, laptop runs, the model for each step, and cost caps. |
| The Google Sheet | Every tab, the columns people own, the Audit and Requests tabs, and how to connect the Sheet. |
| Reference | Every key in config.yaml and _conventions.yaml, the registry entry fields, the CLI, and the comment commands. |
| Troubleshooting | Fixes by symptom: comments that do nothing, stuck checks, CI not running on the agent's commits, licence notes, the live test and the watch. |
Questions about the Tracking Agent
Is the Tracking Agent an analytics tool?
No. It doesn't collect or store events. It checks the code that sends them, keeps the tracking plan in your repo, and reads your analytics tool only to compare what arrived with the plan.
Do I need a tracking plan before installing the Tracking Agent?
No. The install audit drafts the registry from the tracking calls already in your code, and from your analytics data if you connect it. Today's problems go into a baseline, so pull requests are judged only on what they add.
How much does the Tracking Agent cost?
$100 a month for a workspace, or $125 a month together with the Datalyze MCP. Model spend is separate: it goes to your own provider, and every report states it.
What happens to our pull requests if the subscription lapses?
They pass. The check reports that the Tracking Agent is inactive and the pull request wasn't checked, so a missed payment never blocks a release.