Agent Analytics
by @dannyshmueli
Product analytics with your AI agent: set up consent-based tracking, read funnels, paths, retention, experiments, and context, then recommend the smallest gr...
clawhub install agent-analyticsπ About This Skill
name: agent-analytics description: "Headless analytics management for AI builders shipping multi-surface products. Let your agent create projects, install tracking, compare surfaces, query results, and run growth analysis from code, chat, or the terminal." version: 4.0.30 author: dannyshmueli license: MIT repository: https://github.com/Agent-Analytics/agent-analytics-skill homepage: https://agentanalytics.sh compatibility: Requires npx. Browser approval is the normal sign-in path, and detached approval plus finish-code handoff is the default for issue-based runtimes. In Paperclip company-task workflows, always use detached login for the skill path. Normal setup does not require an API key or pasting secrets into chat. tags: - analytics - tracking - web - events - experiments - growth - builders - delegation provides: - capability: analytics - capability: ab-testing - capability: funnels - capability: retention metadata: openclaw: requires: anyBins: - npx
Agent Analytics
Agent Analytics is headless analytics management for AI builders shipping products across many surfaces.
After install, your agent can create projects, install tracking, compare surfaces, query analytics, run experiments, and decide what to fix next without opening a dashboard.
It fits the way builders actually work now: one product often spans the main site, docs, blog, onboarding, free tools, and related properties, and one builder or team often runs more than one product.
English-first workflow, with Chinese docs and content available for OpenClaw users and teams in China.
Use it when you want an agent to operate the day-to-day growth loop across products, portfolios, and surfaces from one conversation, terminal, or code workflow.
The CLI behind this skill is open source and published from:
Hosted free tier includes 100k events/month across 2 projects.
Chinese support / δΈζζ―ζ
/zh/.API, CLI, and MCP, depending on the environment your agent already uses.Mandatory execution policy
npx --yes @agent-analytics/cli@0.5.28 .npx invocation as the primary interface under test in agent environments like OpenClaw and Codex.curl, repo-local scripts, node agent-analytics-cli/..., MCP tools, or a locally installed agent-analytics binary unless the user explicitly asks for one of those paths.npx --yes @agent-analytics/cli@0.5.28 ... commands instead of switching transports.PRO_REQUIRED or a free-tier read cap, explain which deeper read is blocked, keep the workflow on the official CLI path, and use the CLI upgrade-link handoff before rerunning the blocked command.login, do not rely on a localhost callback, and do not auto-open a live interactive browser session on behalf of the task.Delegation support
If the AI agent or client supports subagent delegation, Agent Analytics tasks can benefit from it. Hermes supports this through delegate_task. Other clients should only use the delegation patterns below if they expose an equivalent child-agent capability with isolated context and explicit tool access.
Use delegation when the work naturally splits into independent Agent Analytics workstreams, for example:
Do not delegate when the job is just one CLI command, a simple one-project read, or an auth handoff that should pause cleanly for the human.
Delegation rules for child agents
If delegation is available, every child agent doing live Agent Analytics work must follow the same core rules as the parent:
1. Stay on the pinned official CLI path for live Agent Analytics work:
npx --yes @agent-analytics/cli@0.5.28
2. Preserve prerequisite order:
- install/setup -> identify or create the project, install the project-owned tracker, then verify events
- account-wide questions -> run projects first
- project-specific analysis -> resolve the project, then run context get first
3. Pass concrete context into each child:
- project name or ID
- public URL
- login state
- current activation definition or project context when known
4. Do not switch transports in children:
- no raw API calls, curl, repo-local wrappers, MCP, or a locally installed agent-analytics binary unless the user explicitly asked for that path
5. Do not install generic instrumentation before reviewing the local product flow:
- add only events that map to the user's product goals or a specific workflow in the repo
- do not add duplicate custom events for automatically captured signals like page views, referrers, UTMs, sessions, browser/device, or country
6. Verify before finishing:
- setup children should verify the first useful event
- analysis children should clearly report which top bets are already measurable and which minimal gaps matter now
Recommended delegation pattern for Agent Analytics growth audits
Best default split when the client supports delegation:
Important Hermes note: the default max_concurrent_children is 3. If you want all four workstreams, either:
Delegate by surface or job-to-be-done, not by a generic funnel. For Agent Analytics, the surfaces have different local goals:
The parent agent should synthesize the child outputs in this order: 1. ranked A/B tests and growth bets 2. why these bets matter now 3. surface-specific KPI and CTA recommendations 4. cross-surface funnel narrative 5. minimal instrumentation gaps that matter now
Lead with growth bets before instrumentation details.
Example: delegated Agent Analytics growth audit
Use a split like this when the client supports delegation:
A good parent synthesis for Agent Analytics should answer:
What npx is doing
npx --yes @agent-analytics/cli@0.5.28.npx --yes @agent-analytics/cli@0.5.28 ... form instead of bypassing the CLI.Command format
In OpenClaw, Codex, and similar agent environments, use this exact form:
npx --yes @agent-analytics/cli@0.5.28
For the full command list and flags:
npx --yes @agent-analytics/cli@0.5.28 --help
Do not replace skill examples with agent-analytics in agent runs unless the user explicitly asks to use a locally installed binary.
Managed-runtime auth storage
In OpenClaw and similar managed runtimes, do not rely on the default user-home config path for Agent Analytics auth. Use a persistent runtime/workspace path for every CLI command in the task:
export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/cli@0.5.28 login --detached
npx --yes @agent-analytics/cli@0.5.28 auth status
If shell environment persistence is uncertain, prefix every command instead of relying on export:
AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics" npx --yes @agent-analytics/cli@0.5.28 projects
For one-off debugging, --config-dir "$PWD/.openclaw/agent-analytics" is also valid before or after the command. Before login, make sure .openclaw/ is gitignored. Never commit .openclaw/agent-analytics/config.json.
Safe operating rules
npx --yes @agent-analytics/cli@0.5.28 ... for live queries unless the user explicitly requests API, MCP, or a local binary.query.projects, all-sites, create, stats, insights, events, properties, context, breakdown, pages, paths, heatmap, sessions-dist, retention, funnel, experiments, and feedback.report command in CLI 0.5.28. Produce the final report yourself from fixed-command outputs instead of calling report.query only when the fixed commands cannot answer the question.--filter JSON from raw user text.projects, then run per-project CLI commands as needed.projects prints project IDs. project, update, and delete accept exact project names or project IDs.session_count
- "visitors" means unique_users
- "page views" means event_count filtered to event=page_view
npx --yes @agent-analytics/cli@0.5.28 ... calls.create: ^[a-zA-Z0-9._-]{1,64}$Analytics answer contract
Agent Analytics answers should sound like product and growth analysis, not database output. Lead with the decision, then prove it with the metric.
Use this answer shape for funnels, retention, paths, experiments, attribution, and growth audits:
1. Best bet or diagnosis: the product/growth action or lifecycle issue. 2. Metric definition: population, window, event names, identity basis, and conversion window. 3. Evidence: counts, rates, raw activity, strict survivors, movement, and the biggest driver. 4. Segment, cohort, or surface: where the issue is concentrated. 5. Caveat: identity, sample size, right-censoring, attribution, causality, or instrumentation limits. 6. Next query or action: one bounded follow-up, not a generic list.
Good pattern:
Best bet: fix activation setup friction.
Metric: app onboarding view -> setup copy -> signup -> project_created -> first_event_received within 7d.
Evidence: raw signup/project activity exists, but strict survivors collapse before first_event_received.
Diagnosis: activation bottleneck, not acquisition quality.
Caveat: cross-project identity only counts when portfolio membership and link-domain carrying are configured.
Next: split setup-copy users by selected agent/runtime and first_event_received.
Bad pattern:
Here are the numbers.
Step 1: 100 users
Step 2: 12 users
Conversion: 12%
Metric skepticism rules:
Use analytics lingo deliberately: activation, first value, time to value, cohort, segment, denominator, conversion window, retained activated users, channel quality, guardrail metric, input metric, growth loop, loop constraint, instrumentation gap, tracking plan, identity resolution, directional, right-censored, sample is small, and practical significance.
Avoid vague output: generic "improve onboarding," generic "track more events," "best channel" from signup volume, "retention is up" from WAU alone, and "ship it" from a conversion lift alone.
Closed-loop growth recipe
Use this recipe when the user asks a broad product-growth question like where activation drops, what to fix next, or which experiment to run from current Agent Analytics data.
This is guidance, not a rigid protocol. Skip steps that are already answered or irrelevant, and do not rerun a full activation diagnosis when the user only asks for experiment readout, retention, or a narrow count.
Default order:
1. Resolve the project and auth, then read context get before project-specific analysis.
2. Treat configured activation events in project context as the activation source of truth. If activation is missing, ask for it or configure it; do not guess silently.
3. Discover reality before filters: run properties , properties-received , and recent events as needed so event names and property keys are real.
4. Prefer fixed product-growth commands for broad diagnosis. Do not start broad growth diagnosis with query when context, funnel, paths, breakdown, journey, events, retention, or experiments answer better. Use query only for narrow aggregations that the fixed commands cannot answer.
5. Use funnel for ordered activation leakage. Name the population, window, step events, identity basis, strict survivors, largest absolute loss, and largest relative loss.
6. Use paths for session-local entry, exit, detour, and drop-off behavior around the activation goal. Do not present paths as long-cycle attribution.
7. Use breakdown around the largest leak by practical dimensions that exist in the data: path, source, referrer, CTA label, device, browser, country, campaign, plan, surface, or onboarding step.
8. Use events or journey only for representative inspection or instrumentation sanity when useful; do not dump raw logs by default.
9. Recommend one narrow experiment by default: one CTA, headline, pricing message, onboarding step, or follow-up prompt tied to the business goal event.
10. Recommend a readiness fix instead of an experiment when activation, tracking, sample size, identity/session semantics, or an existing overlapping experiment blocks a trustworthy readout.
11. Read experiments against the business goal event, not exposure count. Decide keep/change/stop/complete with sample-size, causality, and practical-significance caveats.
Preserve the analytics answer contract: diagnosis, metric definition, evidence, segment/surface, caveat, and one bounded next action.
Copyable prompt to hand to another agent:
Use Agent Analytics to diagnose where loses users before activation. Start from project context, use configured activation events as source of truth, discover real events and properties, run funnel and paths, break down the largest leak, inspect representative journeys/events only if useful, then recommend one narrow experiment or the readiness fix that blocks readout. Use the pinned official CLI path and keep the answer to diagnosis, metric definition, evidence, segment/surface, caveat, and one next action.
Experiment readout prompt:
Read for against . Decide whether to keep running it, change it, stop it, or complete it with a winner. Use the business goal event, not exposure count, and include sample-size and causality caveats.
Classification before action
Agent Analytics is project-first and portfolio-aware. Classify scope before you create tracking, query analytics, or recommend instrumentation.
Decision rules:
1. Subdomains are usually surfaces, not projects. Keep app.example.com, docs.example.com, blog.example.com, and www.example.com in one project when they serve the same product learning loop.
2. A mobile app is a surface when it is another client for the same product with the same activation and retention readout. Make it a separate project when it has its own onboarding, lifecycle, release cadence, retention behavior, experiments, or local goals.
3. A free tool is a surface when it is just part of the main product funnel. Make it a separate project when it has its own acquisition loop, completion goal, lead capture, handoff, experiments, or readout.
4. Localhost, local network URLs, branch previews, staging links, and deploy previews are setup or QA surfaces for the intended project. Do not create canonical projects for every preview URL.
5. Separate products under one company or product system should be separate projects under one portfolio when each needs its own activation, retention, lifecycle, release, experiment, or local-goal readout.
6. Newsletter/content pages can be surfaces when they feed the same product loop. A newsletter/content site should be its own project when it has its own content growth loop or local readout. Do not assume native email-service-provider opens or clicks are tracked unless the project explicitly sends those events.
If a domain, subdomain, local URL, preview URL, or mobile app identifier does not match the expected project, do not treat it as immediate failure. Clarify which project and surface the URL belongs to, then map the setup or read back to that intended project. Domains and subdomains are surface URLs or origins, not the project identity.
Command guidance by scope:
create, projects, project, update, stats, insights, events, properties, pages, paths, funnel, retention, experiments, and context get/set.update --origins to add allowed origins for setup or QA surfaces.portfolios list, portfolios create, portfolios get, and portfolios update to define the intentional project membership boundary.data-link-domains for browser-side anonymous ID carrying and portfolios membership for the server-side portfolio scope. Either side alone is incomplete.Canonical docs guide:
Consent-based tracker setup policy
When the user asks to install Agent Analytics, add analytics events, or set up tracking in a repo, use a consent-based, project-owned workflow. Do not guess. Do not overtrack. Do not install generic events that do not map to the user's product goals or a specific workflow in the repo.
In CLI setup, first classify the intended project and surface, then identify the user's setup or production origin, start the normal browser login flow if needed, and create or identify the Agent Analytics project whose allowed_origins includes that origin. Use detached login only for Paperclip, OpenClaw, issue-based or headless runtimes, or when the local browser callback cannot work. The tracker is for the user's own project and account, not for the agent, not for Agent Analytics' internal use, and not for third-party sites.
Treat the base tracker snippet as the start of instrumentation, not the full instrumentation plan. The snippet gives you automatic traffic, source, session, and device context; the agent still needs to review the local product flow and add the few opt-in events that make growth decisions possible.
Use this setup order:
1. Classify the scope: project-local work, a surface of an existing project, or related-project portfolio work.
2. If the user is not logged in, start login. Use login --detached only for Paperclip, OpenClaw, issue-based or headless runtimes, or when the local browser callback cannot work.
3. Create or identify the Agent Analytics project with npx --yes @agent-analytics/cli@0.5.28 create or projects. Treat --domain as the primary surface URL/origin for setup, not as the project identity.
4. Add the exact tracking snippet returned by create or shown in the dashboard for that project.
5. Review the local product flow and choose the smallest named set of meaningful events and tracker opt-ins needed for the user's stated goals.
6. Prefer decision-grade events where relevant: named CTA clicks, signup intent, pricing interactions, checkout progress or completion, install/setup steps, activation milestones, and durable server-side outcome events such as signup_completed, subscription_started, install_completed, project_created, first_event_received, or the product's own activation event.
7. Add optional tracker capabilities only when they unlock a concrete growth decision: data-aa-impression for meaningful section exposure, scroll depth for long-form or landing-page depth questions, form tracking for lead or signup friction, downloads for asset/install intent, vitals/errors/performance for conversion-impacting quality questions, and SPA tracking for client-side route changes.
8. Explain what each event or opt-in enables before or while installing it.
9. Verify the first useful event with npx --yes @agent-analytics/cli@0.5.28 events .
10. Summarize what the installed events now let the user's agent answer.
Page views, paths, referrers, UTMs, device/browser fields, country, session IDs, session count, days since first visit, and first-touch attribution are automatic, so do not add duplicate custom events for those signals. Prefer data-aa-event attributes for named click intent, data-aa-impression for meaningful section exposure, window.aa.track(...) for computed client state, server-side tracking for durable outcomes such as signup_completed, and aa.identify(userId, { email, plan, role, team }) plus aa.set(...) immediately after auth. Use broad script opt-ins like data-track-clicks, scroll depth, errors, forms, downloads, vitals, performance, or SPA tracking only when they unlock a concrete decision for the user's project.
If you need to pass work to another agent, say to use the pinned CLI, create or identify the user's project, install the project-owned tracker with consent, treat the base snippet as the start rather than the end, add only meaningful events tied to the repo's workflows, explain what each event enables, avoid generic tracking, and verify the first useful event.
First-time setup
For Claude Code, Codex, Cursor, and local CLI runtimes, use the authenticated browser setup flow:
npx --yes @agent-analytics/cli@0.5.28 login
npx --yes @agent-analytics/cli@0.5.28 create my-site --domain https://mysite.com
npx --yes @agent-analytics/cli@0.5.28 events my-site --event --days 7 --limit 20
The CLI will open browser approval and wait for the local loopback callback. If the runtime can receive that callback, do not choose detached login just because the work is happening inside an agent.
For Paperclip, OpenClaw, and other issue-based runtimes, login --detached is the preferred first step. It should print the approval URL and exit, so the agent can post the URL to the user without keeping a polling command alive. Wait for the user to sign in with Google or GitHub and reply with the finish code, then run the printed login --auth-request ... --exchange-code ... command and continue with project setup.
The create command returns the exact tracking snippet for the project. Add that returned snippet before