csAdoptionHealth

Local-first customer adoption health dashboard for Splunk Observability Cloud CSMs and TAMs. A composite health score across seven pillars, powered by Claude subagents that read customer telemetry through MCP servers (Pendo, Salesforce, Ghost) and render dashboards you run on your own laptop.

Companion / spiritual sibling of cfallwell/o11y_adoption (the AWS-hosted variant). This repo takes the same conceptual model — pillars, agents, health-score math — and re-homes it as a desktop-web app so field teams can trial it without waiting on shared infrastructure.

Install (Homebrew)

brew install cfallwell/tap/csadoptionhealth
csadoptionhealth

The csadoptionhealth command starts a localhost Fastify server on 127.0.0.1:4319, boots the Next.js dashboard, and opens your default browser to the first-run wizard. Everything — SQLite database, encrypted secrets, per-customer connection profiles — lives on your machine.

Fallback if you're not on the tap yet:

pnpm install -g csadoptionhealth   # or: npm i -g csadoptionhealth
csadoptionhealth

First run

The wizard walks you through:

1. Add a customer — realm (e.g. us1), org_id, an org-admin API Token, and your personal User Token. Tokens go into the OS keychain (macOS Keychain / DPAPI on Windows / libsecret on Linux via keytar); the SQLite metadata row references them by service+account, never in plaintext.
2. Wire up MCP servers — Pendo, Salesforce, and Ghost (Splunk-internal). Ghost auth prefers the ghost auth CLI flow if installed; otherwise a token-paste path is offered. Same keychain rules.
3. Verify — the app pings each MCP endpoint plus api.<realm>.signalfx.com and reports which pillars will light up with what you provided.

See docs/SETUP_FLOW.md for the full state machine.

What's in the box

Layer	Choice	Why
Backend	Fastify on localhost	Small, fast, no cloud coupling
Frontend	Next.js 14 App Router + React + TanStack Query + ECharts + Tailwind	Standard modern stack, ECharts handles the dense time-series work
Storage	SQLite via better-sqlite3 + migrations	Zero-ops, per-user, portable
Secrets	keytar → OS keychain	Never write tokens to disk
Agents	claude -p subprocess with --allowedTools, git worktrees for parallel work	Reuses the Claude Code agent contract
MCP	Pendo, Salesforce, Ghost	Configured per-user in the wizard
Observability	OpenTelemetry SDK → Splunk O11y US1	Full ODD; every feature ships with span + metric defs

See docs/ARCHITECTURE.md for the mermaid diagram and docs/STACK_DECISION.md for the open questions we still owe an answer to (viz alternatives, custom-LLM vs. hosted Claude, per-customer Terraform artifact repo, per-customer OTel config maintenance).

Health score

Seven pillars, weighted, composite 0–100. Same shape as the o11y_adoption program:

• Adoption Breadth (15%)
• Adoption Depth (20%)
• User Engagement (15%)
• Operational Excellence (15%)
• Capacity Health (15%)
• Enablement (10%)
• Value Realization (10%)

Recipes and weights in docs/HEALTH_SCORE_MODEL.md; the underlying metrics in docs/METRICS_CATALOG.md.

Repository layout

apps/
  server/         Fastify localhost API
  web/            Next.js dashboard + first-run wizard
  orchestrator/   Node module that shells out to `claude -p` and manages worktrees
agents/           SKILL.md-style prompt files for each subagent
bin/              csadoptionhealth CLI entry point
docs/             Architecture, health score, pillars, setup flow, security, agents, MCP, observability
otel/             OpenTelemetry collector config + SDK bootstrap
Formula/          Homebrew formula stub
requirements/     Dated requirement docs opened as issues by the researcher agent
.github/          CI, CodeQL, SBOM, reviewer-agent workflows

Development

pnpm install
pnpm dev                 # server + web in parallel
pnpm typecheck && pnpm lint && pnpm test && pnpm build

All PRs are reviewed by the reviewer agent (see .github/workflows/reviewer-agent.yml). See CLAUDE.md for project conventions when working with Claude in this repo.