Tracking Agent docs
Tracking Agent docs: what it does and how it works
The Datalyze Tracking Agent is a Claude Code plugin that keeps your tracking plan, your code and your analytics data in step. On every pull request it proposes the tracking the change needs; a person approves, and it builds and verifies the change on the branch. It runs in your own GitHub Actions with your Anthropic key, or in Claude Code on a laptop. These docs cover setup, the PR check, the audit, the plugin, your data and keys, the Google Sheet and every file and status.
What does the Tracking Agent do?
It does three jobs. The PR check works out what each pull request needs for tracking: new events, changes to existing ones, and anything the change breaks. The audit compares your tracking plan, what your code sends and what your analytics tool received, and explains each problem with evidence. And the plugin lets a developer ask the same questions in Claude Code on their own laptop.
- Pull requestA developer changes the product.
- ProposalThe agent writes what the change needs for tracking, or says it needs nothing.
- ApproveA reviewer edits or rejects items and approves, in Datalyze or with
@datalyze apply. - Build and verifyThe agent changes the plan and the tracking calls, runs the rules, and an independent verifier checks the result.
- MergeThe plan merges with the code, as YAML in
analytics/registry/, and the Google Sheet is rebuilt from it.
Most pull requests need no tracking change. Those pass with "No tracking change needed" and nothing waits for a person. Breaking an existing event is treated as worse than missing a new one, so the existing events a change can reach are checked before anything new is proposed.
How is the Tracking Agent built?
The Tracking Agent is our tracking knowledge and a short description of each job, given to Claude Code, which already knows how to read a codebase, edit files and run commands. Datalyze adds the parts a team needs around it: onboarding, the review and audit screens, the licence and the GitHub App.
| Part | What it is | Where it lives |
|---|---|---|
| The knowledge | Five files on what to track, how events are structured, what goes server side, good and bad tracking, and how Datalyze audits | Datalyze's server, fetched at the start of every run with your workspace key |
| The skills | audit, review and implement: what to do, in what order, and what to write | The public plugin, `joindatalyze/claude-plugins` |
| The verifier | A fresh Claude subagent that checks the work without seeing how it was done | The plugin |
| The tools | Scripts for what must be exact: the plan's rules, the code scan, the analytics snapshot, plan-versus-code-versus-data matching, and checks on the files Datalyze reads | The plugin, served to Claude over MCP |
| The action | joindatalyze/tracking-agent@v2, which runs Anthropic's Claude Code action with the plugin and commits the result | Your GitHub Actions runner |
| The Datalyze app | Onboarding, the review screen and the audit screen (Save, Build it, Continue), and the dashboard | joindatalyze.com, reading and writing your repo through your own GitHub sign-in |
The agent decides, a script enforces, a second agent checks. Hard rules such as naming, vocabulary and plan-versus-code drift are scripts that pass or fail; the verifier is a separate subagent that only sees the diff and the decisions. Anthropic's docs explain how Claude Code plugins work.
Where does the Tracking Agent run?
On your GitHub Actions runner, or on a developer's laptop in Claude Code. Claude runs with your Anthropic key, analytics queries go to your tool with your read-only key, and Datalyze is called only to check your key (which returns the knowledge) and to give each run its GitHub App token. Your data and keys lists everything that goes where.
Two statuses report on each pull request: datalyze/tracking (the agent) and datalyze/rules (scripts, no model). Go live on the Setup page makes both required status checks on your default branch, so a pull request waits until its tracking is approved and built.
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 in mobile apps | Python, Ruby, Go and Java beyond what Claude reads directly: the scan doesn't check them |
| Analytics data | Mixpanel, PostHog and Amplitude through a read-only key; in Claude Code on a laptop, any tool Claude Code is connected to over MCP | Other tools in GitHub Actions |
| Model | Claude, through your Anthropic API key in GitHub Actions, or whatever Claude Code uses on the laptop | Other model providers |
| Writing tracking calls | Through your own wrappers, copying the example calls the first audit records in _tracking_profile.yaml | Running the app to capture what it sends |
| After merge | The Google Sheet rebuilt from the plan on your default branch | Monitoring a release once it ships |
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 | What you need, the onboarding screens, the files and secrets setup adds, the first audit, who can approve, and moving a v1 repo to v2. |
| The PR check and Approve | What the review checks, how to edit and approve a proposal in Datalyze or with a comment, what the build does, and every status. |
| The audit and Fix | What the audit compares, how to run it, what the first audit writes, what each bucket means, and how your answers and picked findings become one fix pull request. |
| The plugin on a laptop | Installing the Datalyze plugin in Claude Code, your own key, what to ask, and how a laptop run differs from one on GitHub. |
| Your data and keys | What stays with you, what Datalyze sees, where each key lives, what the GitHub App and Claude can do, and how approvals are checked. |
| The Google Sheet | The five tabs, the columns people own, how statuses are worked out, connecting the Sheet, and when it updates. |
| Troubleshooting | What each unexpected status, refusal or missing run means, and what to do about it. |
| Reference | Every file the agent keeps in your repo, the config keys, the proposal file, the branches, the plugin's tools and the workflow's triggers. |
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 first audit writes the plan 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 later pull requests are judged only on what they add.
How much does the Tracking Agent cost?
$250 a month for a workspace. Claude's usage is billed to your own Anthropic account. Blocking merges on a private repo needs a paid GitHub plan (Pro, Team or Enterprise), since GitHub offers required checks on private repos only with one; without it the agent still checks and reports on every pull request.
What happens to our pull requests if the subscription lapses?
They pass. The check reports "Tracking Agent inactive, not checked", so a missed payment never blocks a release, and the plugin's skills stop on a laptop until it's renewed.