Customer health score

Customer health score

A health score people trust is one they can read. Every signal, its weight, and what counts as good or bad live in one small JSON file the team owns. The script does the math the same way every week, and every account gets its top drivers so the score leads to an action.

Inputs

1. data/accounts.csv: one row per account. Required: account_id. Useful: name, arr, renewal_date, previous_score (last run's score, for change). Then one column per signal, for example:

   Signal column	From	Example
   seat_utilization	active users / paid seats, last 30 days	0.62
   usage_trend	change in events, last 28 days vs prior 28	-0.12
   core_feature_users	users of the key feature, last 30 days	4
   open_tickets, urgent_tickets_90d, csat	help desk export	2, 0, 4.4
   days_past_due	billing system	32
   exec_sponsor	CRM (1 = yes)	1

   The saas-usage-dashboard JSON output has usage trend and active users per account; use it to fill usage columns.

2. data/health-weights.json: copy examples/weights.json if the user has none. Each signal has column, weight, bad, good, and an optional label and group. A value at bad scores 0, at good scores 100, linear in between and clamped. good can be lower than bad (for tickets and days past due).

Steps

1. Check which signal columns exist and how many accounts have each. Signals with no column are skipped; tell the user.
2. Review the weights with the user before the first run. Defaults: usage 50%, support 25%, billing 15%, relationship 10%. Ask whether that matches how they lose customers; adjust in data/health-weights.json.

3. Run:

   node scripts/health.mjs data/accounts.csv --weights data/health-weights.json --as-of 2026-11-01 --out out/health

4. Report from out/health.md: accounts and ARR per band, the priority accounts (red, or yellow and down 10+ points, renewing within 90 days), and the biggest drops.
5. Sanity check with the user: name two accounts they consider healthy and two they worry about, and see where they landed. If the score disagrees with the team's judgment, adjust weights or thresholds, not individual scores, and rerun.
6. Remind the user to bring this run's score column (in out/health.csv) into next run's accounts file as previous_score, so changes show up.
7. For each priority account, offer the churn-risk-review kit to plan the save.

Rules the script follows

• Score = weighted average of the signals that have a value. Missing values are left out and the weights renormalized.
• Accounts with data for less than 60% of the total weight (min_weight_coverage) are not banded; they show as unknown so a thin record never looks healthy.
• Bands default to green 70+, yellow 45 to 69, red under 45 (bands in the weights file).
• Drivers are the signals scoring under 60, ordered by how many points they cost.

Output template

**Health, Nov 1:** 5 green ($274k), 3 yellow ($138k), 2 red ($50k), 1 not enough data.
Priority (renewing in 90 days): Bluebird Labs (25, down 39; usage trend -68%, seat use 35%), ...
Biggest drops: Bluebird -39, Fable -37, Harbor -33.

Guardrails

• A score is a prompt for a conversation, not a verdict. Never present it to the customer.
• Do not edit a single account's score by hand. Change the weights file and rerun, so every account is treated the same way.
• Do not paste contact names or ticket text into chat.

Customer health score

Combines usage, support, and billing signals into one health score per account, using a weights file your team can read and change. Every account gets a band, its top drivers, its change since last time, and a flag if it is at risk and renewing soon.

Who it is for: customer success leads and founders who want a weekly at-risk list without buying a CS platform.

Example

Input: examples/accounts.csv (11 accounts, 8 signals) and examples/weights.json.

Output (out/health.md):

| **Bluebird Labs** | 25 red | -39 | $42,000 | 44 d | Usage trend (-0.68), Seat use (0.35), Core feature users (1) |

Plus out/health.csv with every account, band, sub-scores by group, and drivers.

What it can access

• Runs node scripts/health.mjs (Node built-ins only).
• Reads data/. Writes data/health-weights.json (your weights) and out/health*.
• No network, no CRM or help desk logins. You bring the exports.

Setup

None. Put one row per account in data/accounts.csv and ask Claude for a health score. It starts from the example weights and tunes them with you.