GrowthScope

AI-first growth product. Provider-agnostic CLI + Skills — your existing coding agent (Claude Code, Cursor, Aider, any) becomes a growth Agent. No dashboards. No vendor lock-in. No server-side LLM.

Cursor 之于代码 = GrowthScope 之于增长.

---

🎯 The pitch

Most analytics tools are dashboard-first. They assume you want to open a browser and stare at charts. We don't.

The reality:

• AI agents (Claude Code, Cursor, Aider, any) can run shell commands but can't navigate websites
• Developers in flow can type but not pivot to chart UIs
• Solo founders / small teams don't have time to log into 5 dashboards a day
• Adding a server-side LLM = vendor lock-in + duplicate cost (your coding agent already has an LLM)

The fix: a provider-agnostic CLI + Skills bridge. Your existing coding agent becomes the growth Agent.

You (in Claude Code / Cursor / any agent):
  "How's MusePod's listen_75 conversion this week vs last?
   If it dropped, what commit might have caused it?"

Your agent (reading our Skills + running Bash):
  → growth --json funnel musepod ...
  → growth --json count_events_by_day ...
  → git log --since=7d
  → synthesizes answer with data + hypothesis

No GrowthScope server-side LLM. Your agent does the reasoning, our CLI provides the data.

That's truly AI-first and provider-agnostic — works with whatever LLM you already use.

---

What's in this repo

growthscope/
├── apps/server/             # Fastify + Postgres + Prisma — analytics ingest + query
├── packages/
│   ├── cli/                 # @growthscope/cli — `growth` binary (the daily driver)
│   ├── sdk-web/             # @growthscope/sdk-web — browser SDK (2.3KB)
│   └── sdk-ios/             # GrowthScope (Swift Package) — mirror, see sister repo
├── skills/                  # Claude Skills — natural language → growth CLI
│   ├── growth-status/       # "how's X doing"
│   ├── growth-funnel-debug/ # "why did X drop" (code-aware)
│   ├── growth-init-product/ # "add HeyCC to growth"
│   └── growth-weekly-report/# "周报"
├── scripts/
│   ├── deploy-prod.sh           # Deploy server side-car to product host
│   ├── install-on-product.sh    # Universal new-product bootstrap (30min)
│   └── deploy-nas.sh            # Optional NAS deployment
├── docs/prd/v1-foundations/ # Moonshot sprint artifacts (architecture decisions)
└── docker-compose.prod.yml  # Side-car co-located with product app

---

Architecture

┌────────────────────────────────────────────────────────────────┐
│  Your products (iOS / Web / any client)                         │
│  MusePod-iOS   HeyCC-iOS    TradeMax-Web    ...                 │
│       │              │             │                            │
│       ├── GrowthScope.track(...)  ← SDK fires async             │
│       │                                                         │
└───────┼─────────────────────────────────────────────────────────┘
        │
        │ HTTPS POST (same-domain, reuses your SSL/nginx)
        ▼
┌────────────────────────────────────────────────────────────────┐
│  Your product's prod server (Pattern B: federated, co-located)  │
│  ┌──────────────────────────────────────────────────────┐      │
│  │ GrowthScope side-car (Docker, ~256MB)                │      │
│  │  - /v1/track / identify (write)                      │      │
│  │  - /v1/events / funnel / retention (read)            │      │
│  │  - /v1/findings (anomalies)                          │      │
│  │  - /v1/admin/anomaly-scan (CLI-triggered)            │      │
│  └──────────────┬───────────────────────────────────────┘      │
│                 │                                                │
│                 ▼                                                │
│  ┌──────────────────────────────────────────────────────┐      │
│  │ Postgres (shared with product DB, isolated user/db)  │      │
│  └──────────────────────────────────────────────────────┘      │
└────────────────────────────────────────────────────────────────┘
        ▲
        │ HTTPS query
        │
┌────────────────────────────────────────────────────────────────┐
│  Developer's machine + AI Agent                                 │
│  ┌──────────────────────────────────────────────────────┐      │
│  │  Terminal: growth events myapp --tail                │      │
│  │           growth funnel myapp a b c                  │      │
│  │           growth --json scan                         │      │
│  └──────────────────────────────────────────────────────┘      │
│  ┌──────────────────────────────────────────────────────┐      │
│  │  Claude Code / Cursor (Agent mode)                   │      │
│  │  Reads ~/.claude/skills/growth-*                     │      │
│  │  "Why did listen_75 drop?" → runs CLI + git log      │      │
│  │  → returns Code-Aware diagnosis + suggested fixes    │      │
│  └──────────────────────────────────────────────────────┘      │
└────────────────────────────────────────────────────────────────┘

Pattern B (Federated): Each product runs its own GrowthScope side-car co-located with the app server. Same-domain SSL, same nginx, zero cross-border latency. CLI multi-target fan-outs across products.

Why not central: NAS / central server adds latency + single point of failure. Each product owns its data on its own server.

---

Quick start

1. Deploy side-car on your product server (30 min)

PRODUCT_SLUG=myapp \
PRODUCT_HOST=root@myapp.com \
EXISTING_PG_CONTAINER=myapp-db \
EXISTING_PG_USER=myapp \
EXISTING_PG_NETWORK=myapp_default \
./scripts/install-on-product.sh

This bootstraps GrowthScope alongside your app, sharing your existing Postgres (new growthscope DB + user) for memory efficiency.

2. Add nginx route

upstream myapp_growthscope { server 127.0.0.1:3050; keepalive 32; }

location /api/growthscope/v1/ {
  proxy_pass http://myapp_growthscope/v1/;
  proxy_set_header Host $host;
}

3. Integrate iOS SDK (from sister repo)

// SPM: github.com/zerolong0/growthscope-ios

import GrowthScope

GrowthScope.configure(
  appId: "myapp",
  endpoint: "https://myapp.com/api/growthscope/v1"
)

GrowthScope.shared.track("any_event", ["k": "v"])

4. Integrate Web SDK (this monorepo)

npm install @growthscope/sdk-web

import { GrowthScope } from '@growthscope/sdk-web';
GrowthScope.configure({ appId: 'myapp-web', endpoint: 'https://myapp.com/api/growthscope/v1' });
GrowthScope.track('signup_start', { source: 'landing' });

5. Use the CLI

npm install -g @growthscope/cli

growth init --name myapp \
  --endpoint https://myapp.com/api/growthscope/v1 \
  --token <admin-token>

growth apps
growth stats myapp
growth events myapp --tail
growth funnel myapp app_open feature_used purchase
growth retention myapp
growth findings
growth scan

Every command supports --json (Agent-friendly) and --quiet (CI-friendly):

growth --json funnel myapp a b c | jq '.funnel[].conversionFromFirst'

No growth ask — your coding agent does that natively by reading Skills + running CLI. Don't pay for a server LLM you already have.

6. Install Claude Skills

ln -s "$(pwd)/skills/growth-status" ~/.claude/skills/growth-status
ln -s "$(pwd)/skills/growth-funnel-debug" ~/.claude/skills/growth-funnel-debug
ln -s "$(pwd)/skills/growth-init-product" ~/.claude/skills/growth-init-product
ln -s "$(pwd)/skills/growth-weekly-report" ~/.claude/skills/growth-weekly-report

Then ask Claude things like:

• "Look at MusePod growth, what's happening this week?"
• "Why did podcast_listen_75 drop on Tuesday?" → runs funnel-debug skill, correlates git commits, gives answer
• "Generate a weekly report across all my products"

---

What's novel

Capability	What's different
Provider-agnostic	Zero LLM dep on server. Use Claude / GPT / Llama / DeepSeek — whatever your coding agent uses
Code-Aware Analytics	Your agent reads metric drop → reads git log → "commit 0a1b2c on 5/22 likely broke this"
Proactive Pre-compute	Anomaly worker writes findings to DB → agent surfaces them instantly via list_findings
Cross-Product Mining	Your agent multi-targets via ~/.growthrc — sees patterns across all your products
CLI > Dashboard	Agents run CLI but can't navigate browsers; CLI is the natural surface
Skills, not MCP	4 markdown files in skills/ — any AI tool that can read Markdown + run Bash uses them
Knowledge Compounding	Findings persist; agent's memory of your app grows over time

---

V1 status

Feature	Status
Server Foundation	✅
iOS SDK	✅
Web SDK	✅
CLI (provider-agnostic, --json mode)	✅
4 Claude Skills	✅
Anomaly Detection (CLI-triggered)	✅
MusePod E2E integration	✅
Universal product bootstrap	✅

Why no growth ask natural-language command?

Previous V1.1 prototype embedded an LLM in the server and did growth ask "..." → server LLM loops over tools → returns answer.

Removed because:

• Locks the server into one LLM provider (vendor lock-in)
• Duplicates what your coding agent already does (you pay twice)
• Violates "AI-first + provider-agnostic" principle

The right pattern: coding agent (Claude Code / Cursor / Aider / etc.) reads Skills, runs CLI commands itself. Same result, your existing LLM, zero server LLM cost.

If you really need an LLM-driven endpoint (e.g. Telegram bot, automated cron alerts), wire one yourself — POST /v1/track and GET /v1/events are HTTP, plug any LLM you like in front.

---

Sister repo

• 🟢 growthscope-ios — Swift Package (must be standalone for SPM)

---

Roadmap

• V1.x: Continuous Hypothesis Generation Agent, Cross-Product Pattern AI, Live "Why" explanations, NL Cohort queries
• V1.2: Semantic Event Understanding (auto-classify events), Knowledge Compounding (Agent memory of your business)
• V2.0: Counterfactual reasoning ("if user X had seen new flow"), Auto-fix PR round trip (Agent finds + fixes + ships)

---

License

MIT © 2026 zerolong0