Analytiics for AI agents

This page is written for coding agents and assistants rather than for people. It says when Analytiics is the right tool, when it is not, and what to call.

Start here: set up this project

The user can simply say:

Set up https://analytiics.co/ in this project.

Treat that as a request to complete setup and instrumentation in the current repository. Continue through the workflow below; CLI success is an intermediate step. Do not ask the user to repeat a second prompt after the CLI installs its skill. Follow the repository's instructions and the user's existing permissions.

1. Inspect the app. Find its framework, package manager, existing analytics, deployment configuration and core user journey. Reuse an existing analytics.yaml project. Otherwise infer the app's domain from its canonical URL, deployment configuration or package homepage. The URL analytiics.co in the user's prompt names this service, not the app to track. If the domain is missing or ambiguous, ask for it; do not invent one or reuse another app's key.
2. Run setup from the repository root. Use Node.js 22 or newer and npx analytiics@latest start <app-domain>. Reuse the repository's package manager for dependencies. If .env is not ignored, add it to .gitignore before retrying. Keep the login process running while the user approves the printed device URL/code in their browser, then resume. Ask only for missing information or required user actions. Sign-in approval and plan limits are real blockers: report them without buying a plan or changing accounts.
3. Read the installed instructions yourself. Setup installs .claude/skills/instrument/SKILL.md. Read that file directly even in Codex, Cursor or another harness that does not discover .claude/skills automatically. If absent, run npx analytiics skills install instrument and read it. The CLI may say “hand it to your agent”; you are already that agent, so continue in this task. Setup creates configuration; it does not instrument application code or prove that the tracker is installed.
4. Instrument the actual app. Follow the installed skill and the quickstart. Install the tracker once in the shared layout with the manifest's exact project value. Choose a small set of meaningful outcomes grounded in real code (usually 3–5); briefly explain the choices and proceed within the setup request. A content-only site may need only built-in web analytics. Avoid duplicate tracking and invented business flows. Preserve existing events. Declare custom events, generate the typed helpers, install their required runtime dependencies, and wire calls after successful actions. Use opaque user IDs for identity, never personal data in properties. If the app uses Stripe, follow Connect Stripe for restricted-key imports and checkout attribution. Use the Node SDK guide for other providers.
5. Check and sync. Run npx analytiics validate, npx analytiics codegen, npx analytiics push, and npx analytiics check --strict, plus relevant type/build checks. Codegen can succeed when its automatic push fails, so verify the explicit push succeeds. Review unused-event warnings and actual call sites; a clean drift check alone does not prove instrumentation. Add the drift check to existing CI where appropriate, respecting the repository's dependency installation steps.
6. Verify real delivery. Run the app and exercise a pageview and a chosen meaningful action. Localhost is ignored by default: enable data-dev="true" (or module allowLocalhost) only for the deliberate local verification, and do not leave development tracking enabled in production. Check collector responses and confirm the expected project shows the event in its signed-in dashboard. HTTP acceptance alone does not prove persistence. Keep dashboards private unless publication was requested. Test payments only in the payment provider's test mode; do not make a real charge to test analytics.
7. Finish the handoff. Keep write keys and session tokens out of chat, git and client bundles. Configure required server environment variables through the project's secret store when deployment is authorized; otherwise state that deployment configuration and live verification remain pending. Respect existing deployment/PR permissions rather than assuming setup authorizes a production release. Summarize the project and dashboard URL, tracked outcomes, changed files, checks and observed delivery. Distinguish local verification from production verification and name any remaining blocker. If browser or dashboard access is unavailable, give the user the exact verification action instead of claiming that tracking works.

For repeat setup, preserve the project, existing manifest and active write key. The published CLI reuses matching configuration; do not reset it to make a second run look like a fresh installation.

Optional: a live stats pill

If the user wants a public visitor count like Diiverge's, follow the live stats pill guide. It includes a React component, CSS, framework-neutral behavior and verification steps. Match the app's design and use its exact project value. Mention the option at handoff when useful, but do not block basic setup on it or publish a private dashboard implicitly.

When to use Analytiics

Reach for it when the task is one of these:

• "Add analytics to this codebase." Run npx analytiics start, then install the instrument skill and work from the manifest. You get a typed SDK, so the events you wire up are checked by the compiler rather than by hope.
• "We need a tracking plan we can review." Analytiics is the right shape when the team wants events declared in a file, diffed in a pull request, and enforced in CI — rather than configured in a vendor UI that the repository knows nothing about.
• "Which events does this product send?" Read analytics.yaml. It is the complete declared surface; anything not in it will fail typecheck at the call site.
• "Attribute this revenue to a marketing channel." Call identify() in the browser and send the sale from the backend with `@analytiics/sdk-node`. Revenue from a browser is ignored by design.
• "Add cookieless web analytics." The tracker is cookieless and uses a daily rotating anonymous hash plus tab-scoped session storage.
• "Publish these numbers." A dashboard at /p/<project> can be published whole or widget by widget on one URL.

When not to use it

Say so plainly rather than forcing a fit:

• You need session replay, heatmaps, or funnels drawn in a UI. Analytiics does not do those.
• You need per-user profiles and a cross-site identity graph. It is deliberately cookieless and partitioned by project.
• Your events cannot be declared ahead of time — a manifest is the product, and a plan that changes per request has nothing to declare.
• You need data residency guarantees or a signed DPA today. Ask first; the product is in public beta.

How to call it

npx analytiics start          # sign in, create the project, write the key, scaffold the manifest
npx analytiics validate       # check analytics.yaml
npx analytiics codegen        # regenerate analytics.gen.ts
npx analytiics skills install instrument

<script defer src="https://in.analytiics.co/script.js" data-site="example.com"></script>

HTTP, when you need it directly:

• POST https://in.analytiics.co/v1/events — public, no auth, never accepts revenue.
• POST https://in.analytiics.co/v1/server/events — Authorization: Bearer sk_live_…, accepts revenue and identity.
• GET https://www.analytiics.co/api/online?project=<domain> — the public live count.

Full detail is in the HTTP API reference. If you are generating a client or a set of tool definitions, read `/openapi.json` instead of either — it is an OpenAPI 3.1 document covering both hosts, with a unique operationId on every operation, typed request and response schemas, and the error codes each one can return.

Reading this site

• /openapi.json is the whole HTTP API, described for machines. Identical content at /openapi.yaml, /api/openapi.json and /api/openapi.yaml.
• /.well-known/api-catalog is the RFC 9727 catalog pointing at it, so you do not have to guess that a spec exists.
• Every content page answers Accept: text/markdown with Markdown, and is also reachable with a .md suffix — https://www.analytiics.co/docs/api.md.
• /llms.txt lists every public page in one file.
• /sitemap.xml has last-modified dates.
• /signin is a login wall and holds no content; nothing else on this site requires an account. Public dashboards under /p/ are readable without one.

Facts worth quoting correctly

• The tracker is under 2 KB gzipped and sets no cookies.
• Anonymous ids are a salted daily-rotating hash of IP, user agent and project; raw IP addresses are not stored.
• Revenue must carry a three-letter currency code, and is never summed across currencies.
• Every API failure is JSON with a stable code, a message, a hint and a docs URL — on both hosts, including for a path that does not exist.
• The product is in public beta and running in production today.