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.

By Ansh AgrawalUpdated

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.

  1. Pull requestA developer changes the product.
  2. ProposalThe agent writes what the change needs for tracking, or says it needs nothing.
  3. ApproveA reviewer edits or rejects items and approves, in Datalyze or with @datalyze apply.
  4. Build and verifyThe agent changes the plan and the tracking calls, runs the rules, and an independent verifier checks the result.
  5. 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.

PartWhat it isWhere it lives
The knowledgeFive files on what to track, how events are structured, what goes server side, good and bad tracking, and how Datalyze auditsDatalyze's server, fetched at the start of every run with your workspace key
The skillsaudit, review and implement: what to do, in what order, and what to writeThe public plugin, `joindatalyze/claude-plugins`
The verifierA fresh Claude subagent that checks the work without seeing how it was doneThe plugin
The toolsScripts 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 readsThe plugin, served to Claude over MCP
The actionjoindatalyze/tracking-agent@v2, which runs Anthropic's Claude Code action with the plugin and commits the resultYour GitHub Actions runner
The Datalyze appOnboarding, the review screen and the audit screen (Save, Build it, Continue), and the dashboardjoindatalyze.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?

AreaAvailable nowNot available yet
LanguagesTypeScript and JavaScript for web apps, Node servers and React Native; Swift, Kotlin and Dart in mobile appsPython, Ruby, Go and Java beyond what Claude reads directly: the scan doesn't check them
Analytics dataMixpanel, PostHog and Amplitude through a read-only key; in Claude Code on a laptop, any tool Claude Code is connected to over MCPOther tools in GitHub Actions
ModelClaude, through your Anthropic API key in GitHub Actions, or whatever Claude Code uses on the laptopOther model providers
Writing tracking callsThrough your own wrappers, copying the example calls the first audit records in _tracking_profile.yamlRunning the app to capture what it sends
After mergeThe Google Sheet rebuilt from the plan on your default branchMonitoring 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?

PageWhat it answers
SetupWhat 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 ApproveWhat 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 FixWhat 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 laptopInstalling 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 keysWhat 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 SheetThe five tabs, the columns people own, how statuses are worked out, connecting the Sheet, and when it updates.
TroubleshootingWhat each unexpected status, refusal or missing run means, and what to do about it.
ReferenceEvery 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.