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.
Which files does the Tracking Agent keep in my repo?
| File | What it is | Who changes it |
|---|---|---|
.github/workflows/datalyze.yml | The workflow | Setup, then your team |
.datalyze/config.yaml | Where the plan is, who may approve, and the analytics tool | Your team (never the agent) |
.datalyze/context.md | What your team told the agent about the product | Your team, or the Setup page |
.datalyze/proposals/pr-<n>.json | A pull request's proposal, with the reviewer's decisions | The review, then the reviewer in Datalyze |
analytics/registry/<area>.yaml | The events of one product area | The agent, in approved pull requests, and your team |
analytics/registry/_conventions.yaml | Naming rules, over the Datalyze defaults | Your team only |
analytics/registry/_properties.yaml | The shared property vocabulary, with synonyms | The first audit, then approved changes |
analytics/registry/_user_properties.yaml, _super_properties.yaml, _identity.yaml | User properties, properties on every event, and identify, alias and reset | The first audit, then approved changes |
analytics/registry/_tracking_profile.yaml | Your SDKs, wrappers and an example of each call, for the scan and for writing calls in your style | The audit |
analytics/registry/_baseline.json | Problems accepted on the first audit, so later changes are judged on what they add | The first audit only |
analytics/.datalyze/audit.json, audit.md | The latest audit, for the audit screen and for people | Each audit, on the datalyze/audit branch |
CLAUDE.md (Datalyze's block) | Sends tracking questions to the plugin | Setup |
.claude/settings.json | Offers the plugin in Claude Code | Setup |
.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?
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| Key | What it does |
|---|---|
registry | The folder of the tracking plan. Default analytics/registry |
reviewers | Who may approve, with Approve or @datalyze apply. Read from the base branch |
analytics.tool, project_id, region, host | The analytics tool the audit reads, read-only. host is PostHog's |
analytics.environment_property, production_values | Only production traffic counts: the property naming the environment, and its production value or values |
sheet.url_env, sheet.token_env | Other 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?
| Branch | What's on it |
|---|---|
datalyze/setup | The setup pull request, and Setup's later changes |
datalyze/first-plan | The first audit's plan pull request; merging it approves the plan |
datalyze/audit | The 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?
| Tool | What it does |
|---|---|
knowledge | Checks the licence with DATALYZE_KEY and returns the five knowledge files |
registry | Reads the tracking plan |
validate | The plan's hard rules: naming, vocabulary and structure |
scan | The tracking calls in the code against the plan, and the drift between them |
snapshot | What Mixpanel, PostHog or Amplitude received, through a read-only key |
match | Plan against code against data: one bucket per event and user property |
check_proposal, check_audit | Check the two files Datalyze's screens read |
vocabulary, baseline | First audit only: write _properties.yaml from the plan, and accept today's problems in _baseline.json |
When does the Datalyze workflow run?
| Event | What runs |
|---|---|
| A pull request is opened, pushed to, reopened or marked ready | datalyze/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 branch | The Google Sheet sync, or the first audit when there's no plan yet |
| A run started from Datalyze or the Actions tab | audit, 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.