Tracking Agent docs

Tracking Agent reference: files, config and tools

The Tracking Agent keeps your tracking plan in your repo, as YAML in analytics/registry/, with its settings and proposals in .datalyze/. This page lists every file, the config keys, what a proposal holds, the branches, the plugin's tools and when the workflow runs. The registry is the source of truth; the Google Sheet is a view of it.

By Ansh AgrawalUpdated

Which files does the Tracking Agent keep in my repo?

FileWhat it isWho changes it
.github/workflows/datalyze.ymlThe workflowSetup, then your team
.datalyze/config.yamlWhere the plan is, who may approve, and the analytics toolYour team (never the agent)
.datalyze/context.mdWhat your team told the agent about the productYour team, or the Setup page
.datalyze/proposals/pr-<n>.jsonA pull request's proposal, with the reviewer's decisionsThe review, then the reviewer in Datalyze
analytics/registry/<area>.yamlThe events of one product areaThe agent, in approved pull requests, and your team
analytics/registry/_conventions.yamlNaming rules, over the Datalyze defaultsYour team only
analytics/registry/_properties.yamlThe shared property vocabulary, with synonymsThe first audit, then approved changes
analytics/registry/_user_properties.yaml, _super_properties.yaml, _identity.yamlUser properties, properties on every event, and identify, alias and resetThe first audit, then approved changes
analytics/registry/_tracking_profile.yamlYour SDKs, wrappers and an example of each call, for the scan and for writing calls in your styleThe audit
analytics/registry/_baseline.jsonProblems accepted on the first audit, so later changes are judged on what they addThe first audit only
analytics/.datalyze/audit.json, audit.mdThe latest audit, for the audit screen and for peopleEach audit, on the datalyze/audit branch
CLAUDE.md (Datalyze's block)Sends tracking questions to the pluginSetup
.claude/settings.jsonOffers the plugin in Claude CodeSetup

.datalyze/report.md is the report a run posts as its comment; it's never committed. A _map/ folder from v1 is ignored.

What goes in .datalyze/config.yaml?

yaml
registry: analytics/registry
reviewers: []          # GitHub logins or @org/team; empty: anyone with write access
analytics:
  tool: mixpanel        # mixpanel, posthog or amplitude
  project_id: "2317312"
  region: us            # us, eu or in
  environment_property: env
  production_values: production
KeyWhat it does
registryThe folder of the tracking plan. Default analytics/registry
reviewersWho may approve, with Approve or @datalyze apply. Read from the base branch
analytics.tool, project_id, region, hostThe analytics tool the audit reads, read-only. host is PostHog's
analytics.environment_property, production_valuesOnly production traffic counts: the property naming the environment, and its production value or values
sheet.url_env, sheet.token_envOther secret names for the Apps Script Sheet receiver

What's in a tracking proposal file?

A proposal is JSON with a verdict (no_change or changes_proposed), the items, the existing events it checked and why each is unaffected, and questions. Each item has a kind (event, event property, user property, super property or identity), an action (add, extend, modify or deprecate), its target, the complete proposed entry with real example values, whether it's breaking, and evidence: a file and line with the code quoted, or a query and its result.

The reviewer adds decision, note and edits per item, and answer per question; approving adds approved_by. The build marks each built item implemented.

Which branches does the Tracking Agent use?

BranchWhat's on it
datalyze/setupThe setup pull request, and Setup's later changes
datalyze/first-planThe first audit's plan pull request; merging it approves the plan
datalyze/auditThe latest audit's two files, replaced each time
datalyze/fix-audit-<date>One fix pull request per audit: your answers, the findings you picked and your note, from the audit screen

Which tools does the Datalyze plugin give Claude?

ToolWhat it does
knowledgeChecks the licence with DATALYZE_KEY and returns the five knowledge files
registryReads the tracking plan
validateThe plan's hard rules: naming, vocabulary and structure
scanThe tracking calls in the code against the plan, and the drift between them
snapshotWhat Mixpanel, PostHog or Amplitude received, through a read-only key
matchPlan against code against data: one bucket per event and user property
check_proposal, check_auditCheck the two files Datalyze's screens read
vocabulary, baselineFirst audit only: write _properties.yaml from the plan, and accept today's problems in _baseline.json

When does the Datalyze workflow run?

EventWhat runs
A pull request is opened, pushed to, reopened or marked readydatalyze/rules, and the review
A comment starting @datalyze@datalyze apply builds the proposal; anything else is a free-form request
A push to the default branchThe Google Sheet sync, or the first audit when there's no plan yet
A run started from Datalyze or the Actions tabaudit, implement (a pull request's proposal or picked findings) or review

Run names say what each run is for, such as Datalyze: implement #5 or Datalyze: audit, so the dashboard can tell them apart. GitHub lists the events that trigger workflows.

Questions about the reference

Can we move the registry out of analytics/registry?

Yes. Set registry in .datalyze/config.yaml and move the folder in the same pull request. The audit's files then go in a .datalyze/ folder beside the new registry folder.

Can we edit the registry by hand?

Yes. It's plain YAML, and datalyze/rules checks every change. A hand edit that already matches what a pull request needs means the review proposes nothing for it.

Where are the tracking plan's naming rules?

In analytics/registry/_conventions.yaml, over the Datalyze defaults: snake_case object_action names such as post_created. The playbook chapter on creating a tracking plan covers choosing a convention, and our analytics setup service sets one up with you.