@coniv/auto-ga4

In-app analytics orchestration overlay and local agent bridge for React/SPA projects.

The package gives planners a floating button inside a running app. They can select a UI element, describe the event they want, save repository and analytics settings locally, send the request to a local Codex/Claude workflow, review the generated diff, and create a PR against the configured target branch.

What It Includes

• Browser SDK with:
  • floating action button
  • DOM highlight and element selection mode
  • request form for event name, params, and notes
  • local orchestrator settings form
  • job status panel with diff review and PR approval
  • JSON export fallback when the local orchestrator is offline
• Local CLI orchestrator with:
  • auto-ga4-agent init
  • auto-ga4-agent start
  • persisted local settings
  • built-in Codex and Claude execution presets
  • queued jobs with diff review state
  • GitHub PR creation after approval

Install

npm install @coniv/auto-ga4

Quick Start

1. Create the local orchestrator config

npx auto-ga4-agent init

This creates .auto-ga4/agent.config.json.

Example:

{
  "projectId": "coniv-web",
  "repoUrl": "https://github.com/example/coniv-web.git",
  "baseBranch": "main",
  "storageDir": "/absolute/path/to/.auto-ga4/requests",
  "workspaceDir": "/absolute/path/to/your/frontend/repo",
  "agentProvider": "codex",
  "trackingStrategy": "gtm-first",
  "postReceiveCommand": "",
  "githubToken": "",
  "ga4PropertyId": "123456789",
  "ga4DataStreamId": "987654321",
  "ga4MeasurementId": "G-XXXXXXXXXX",
  "gtmAccountId": "1234567",
  "gtmContainerId": "GTM-XXXXXXX",
  "gtmWorkspaceId": "1",
  "keychainNote": "Prefer storing secrets in your OS keychain or another secret manager. This local config file may still contain tokens for v0.2.0 automation."
}

agentProvider supports codex, claude, custom, and none.

• codex: writes a prompt file and launches codex exec inside the configured workspace
• claude: writes a prompt file and launches Claude Code against the configured workspace
• custom: use postReceiveCommand
• none: save-only mode; the browser UI will fall back to JSON export

If you need full control, set postReceiveCommand manually. Supported placeholders are {{promptFile}} and {{workspaceDir}}.

2. Start the local orchestrator

npx auto-ga4-agent start

The browser overlay talks to http://127.0.0.1:4417 by default.

3. Mount the overlay in your app

import { initAutoGa4 } from "@coniv/auto-ga4";

initAutoGa4({
  projectId: "coniv-web",
  defaultRepoUrl: "https://github.com/example/coniv-web.git",
  defaultBaseBranch: "main",
  agentEndpoint: "http://127.0.0.1:4417"
});

4. Or use the React wrapper

import React from "react";
import { AutoGa4Provider } from "@coniv/auto-ga4/react";

export function AppShell({ children }) {
  return (
    <AutoGa4Provider
      config={{
        projectId: "coniv-web",
        defaultRepoUrl: "https://github.com/example/coniv-web.git",
        defaultBaseBranch: "main"
      }}
    >
      {children}
    </AutoGa4Provider>
  );
}

User Flow

1. Start auto-ga4-agent.
2. Open the floating panel and save local settings:
   • repo URL
   • target branch
   • workspace directory
   • agent provider
   • GitHub token for PR creation
   • GA4 and GTM identifiers
3. Select a UI element.
4. Fill in the event name, params, and implementation notes.
5. Click Queue orchestration job.
6. Wait for the local coding agent to finish.
7. Review the diff summary shown in the panel.
8. Click Approve diff and create PR.

Local Orchestrator Endpoints

• GET /health
• GET /settings
• PUT /settings
• GET /jobs
• GET /jobs/:id
• POST /jobs
• POST /jobs/:id/approve

Request Payload Shape

{
  "kind": "auto-ga4.request",
  "version": 1,
  "createdAt": "2026-03-31T09:00:00.000Z",
  "request": {
    "projectId": "coniv-web",
    "repoUrl": "https://github.com/example/coniv-web.git",
    "baseBranch": "main",
    "agentEndpoint": "http://127.0.0.1:4417",
    "eventName": "click_pricing_cta",
    "eventDescription": "Track pricing CTA clicks",
    "params": {
      "button_name": "pricing_cta"
    },
    "notes": "Open a PR against main",
    "selection": {
      "tagName": "button",
      "text": "Start free trial",
      "selector": "#hero-cta",
      "role": "button",
      "ariaLabel": "",
      "href": "",
      "routePath": "/pricing",
      "componentHint": "",
      "dataTestId": "hero-cta",
      "dataset": {},
      "attributes": {}
    },
    "page": {
      "url": "http://localhost:3000/pricing",
      "title": "Pricing",
      "pathname": "/pricing",
      "timestamp": "2026-03-31T09:00:00.000Z"
    }
  }
}

Public API

Browser

• initAutoGa4(config)
• openAutoGa4Panel()
• destroyAutoGa4()

React

• AutoGa4Provider
• useAutoGa4()

Agent

• createAgentServer(options)
• runCli(argv)

Current Scope

• Best suited for React/SPA projects
• Uses a local coding agent to apply analytics changes and prepare code review
• Supports review-first PR creation from the browser panel
• Stores only local orchestrator settings and job metadata
• Passes GA4 and GTM identifiers to the local orchestration flow

Not Yet Built In

• Direct Google OAuth in the browser panel
• Native GA4 or GTM API adapters inside this package
• Automatic GA4 dashboard reporting beyond linking the work into your existing GA4 setup

For GA4 or GTM automation, the local provider environment should have the relevant MCP servers or custom commands already configured.