Skip to Content
TrichiDataTrichiData

Agent rules

Ready-to-commit rule files that keep TrichiData tracking correct as AI agents change your app.

After the first install, every feature written by an AI agent can break or skip tracking. Commit one of the rule files below so the agent keeps events consistent.

All snippets say the same thing: add events for new flows, identify users with the auth user id, never send PII, and verify with the verify_events MCP tool when it is available (new, see Install with your AI assistant).

AGENTS.md

Append to AGENTS.md at the repository root:

## TrichiData analytics

This app uses TrichiData (SDK >= 0.6.0). Keep tracking correct when you change the code.

- The client is created once at the app root. Never create a second client.
- Page views are automatic (`autoPageviews`). Do not add manual `page()` calls unless
  `autoPageviews` is set to `false`. In React Native use `trackScreen()` or the
  navigation handlers.
- When you add a new user flow (sign-up, login, onboarding step, checkout, payment,
  subscription, key feature use), add an event for it. Prefer the standard helpers
  (`signedUp`, `loggedIn`, `checkoutStarted`, `orderCompleted`, ...) and use
  `trackCustom('snake_case_name', props)` otherwise.
- After login or sign-up call `identify({ userId })` with the auth user id. Call `reset()`
  on logout.
- Never send PII (email, name, phone, address, free text) in properties or `userId`.
- Stripe: always set `metadata.user_id` (and `client_reference_id` on Checkout Sessions)
  to the same auth user id.
- Server code: call `await client.flush()` before the process or request ends. Do not share
  one client across concurrent requests for different users.
- The API key comes from an environment variable. Never hardcode it.
- If the TrichiData MCP server is available, call `get_tracking_plan` before adding events
  and `verify_events` after, then report what arrived.

Cursor

Save as .cursor/rules/trichidata.mdc:

---
description: Keep TrichiData analytics tracking correct
alwaysApply: true
---

This app uses TrichiData (SDK >= 0.6.0).

- One client, created at the app root. Do not create another.
- Page views are automatic. Do not add manual `page()` calls unless `autoPageviews` is false.
  React Native: use `trackScreen()` or `getTrichiDataNavigationHandlers`.
- New user flow (sign-up, login, checkout, payment, subscription, key feature) means a new
  event. Use standard helpers (`signedUp`, `loggedIn`, `checkoutStarted`, `orderCompleted`)
  or `trackCustom('snake_case_name', props)`.
- After login/sign-up: `identify({ userId })` with the auth user id. On logout: `reset()`.
- Never put PII (email, name, phone, address, free text) in event properties or `userId`.
- Stripe objects must carry `metadata.user_id` (and `client_reference_id` for Checkout Sessions).
- Server code: `await client.flush()` before exit.
- API key from an env variable, never hardcoded.
- If the TrichiData MCP server is connected, run `get_tracking_plan` before and
  `verify_events` after changing tracking.

Claude Code

Append to CLAUDE.md:

## TrichiData analytics

Tracking uses TrichiData (SDK >= 0.6.0). When you add or change a user-facing flow:

1. Add an event for it (standard helper such as `signedUp`, `loggedIn`, `checkoutStarted`,
   `orderCompleted`, or `trackCustom('snake_case_name', props)`).
2. Identify users with `identify({ userId })` using the auth user id; call `reset()` on logout.
3. Never send PII (email, name, phone, address, free text).
4. Do not add manual `page()` calls while `autoPageviews` is on.
5. Stripe: set `metadata.user_id` and `client_reference_id` to the auth user id.
6. Server code: `await client.flush()` before the process ends.
7. If the `trichidata` MCP server is connected, call `get_tracking_plan` first and
   `verify_events` afterwards, and tell me what is still missing.

To connect the MCP server, see Path A.

Lovable / Bolt knowledge

Paste into Project knowledge (Lovable) or the project prompt / rules (Bolt). These tools may not support custom MCP servers. If they do not, confirm events in Live events in your TrichiData project.

Analytics: this app uses TrichiData (@trichidata/react, version 0.6.0 or newer).

Rules for every change you make:
- The TrichiDataProvider wraps the app once, with the project API key from an environment
  variable. Do not add a second provider or client.
- Page views are tracked automatically. Do not add manual page() calls unless
  autoPageviews is set to false.
- When you build a new flow (sign-up, login, checkout, payment, subscription, a key
  feature), add a tracking event for it. Use client.signedUp, client.loggedIn,
  client.checkoutStarted, client.orderCompleted, or client.trackCustom("snake_case_name", props).
- After login or sign-up, call client.identify({ userId }) with the Supabase auth user id
  (auth.users.id). On logout call client.reset().
- Never send personal data (email, name, phone, address, free text) in event properties
  or in userId.
- For Stripe, set metadata.user_id and client_reference_id to the same auth user id.
- After changes, tell me which events were added so I can confirm them in the TrichiData
  dashboard.

See also

On this page