burnwatch 0.1.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "burnwatch",
+  "version": "0.1.0",
+  "description": "Passive cost memory for vibe coding — detects paid services, tracks spend, injects budget context into your AI coding sessions.",
+  "type": "module",
+  "bin": {
+    "burnwatch": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "registry.json",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup && node -e \"const fs=require('fs');const f='dist/cli.js';const c=fs.readFileSync(f,'utf8');if(!c.startsWith('#!')){fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)}\"",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude-code",
+    "cost-tracking",
+    "saas",
+    "spend",
+    "budget",
+    "developer-tools",
+    "ai",
+    "vibe-coding",
+    "finops"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}

package/registry.json

@@ -0,0 +1,330 @@
+{
+  "$schema": "./registry.schema.json",
+  "version": "0.1.0",
+  "lastUpdated": "2026-03-24",
+  "services": {
+    "anthropic": {
+      "id": "anthropic",
+      "name": "Anthropic (Claude)",
+      "packageNames": ["@anthropic-ai/sdk", "anthropic"],
+      "envPatterns": ["ANTHROPIC_API_KEY", "ANTHROPIC_ADMIN_KEY"],
+      "importPatterns": ["@anthropic-ai/sdk", "anthropic"],
+      "mentionKeywords": ["anthropic", "claude", "claude-3", "claude-4", "sonnet", "opus", "haiku"],
+      "billingModel": "token_usage",
+      "scalingShape": "linear",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.anthropic.com/v1/organizations/usage",
+      "pricing": {
+        "formula": "input_tokens * input_rate + output_tokens * output_rate",
+        "unitName": "token"
+      },
+      "gotchas": [
+        "Admin API key required for billing data — standard API key only allows inference",
+        "Costs vary significantly by model: Haiku ~$0.25/MTok, Sonnet ~$3/MTok, Opus ~$15/MTok"
+      ],
+      "alternatives": ["openai", "google-gemini"],
+      "docsUrl": "https://docs.anthropic.com/en/api/usage",
+      "lastVerified": "2026-03-24"
+    },
+    "openai": {
+      "id": "openai",
+      "name": "OpenAI",
+      "packageNames": ["openai"],
+      "envPatterns": ["OPENAI_API_KEY", "OPENAI_ORG_ID"],
+      "importPatterns": ["openai"],
+      "mentionKeywords": ["openai", "gpt-4", "gpt-5", "chatgpt", "dall-e", "whisper"],
+      "billingModel": "token_usage",
+      "scalingShape": "linear",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.openai.com/v1/organization/usage",
+      "pricing": {
+        "formula": "input_tokens * input_rate + output_tokens * output_rate",
+        "unitName": "token"
+      },
+      "gotchas": [
+        "Organization-level API key may be needed for usage data",
+        "Image generation (DALL-E) billed per image, not per token"
+      ],
+      "alternatives": ["anthropic", "google-gemini"],
+      "docsUrl": "https://platform.openai.com/docs/api-reference/usage",
+      "lastVerified": "2026-03-24"
+    },
+    "google-gemini": {
+      "id": "google-gemini",
+      "name": "Google Gemini",
+      "packageNames": ["@google/generative-ai", "@ai-sdk/google"],
+      "envPatterns": ["GEMINI_API_KEY", "GOOGLE_AI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+      "importPatterns": ["@google/generative-ai", "@ai-sdk/google"],
+      "mentionKeywords": ["gemini", "google ai", "google-gemini"],
+      "billingModel": "token_usage",
+      "scalingShape": "linear",
+      "apiTier": "calc",
+      "pricing": {
+        "formula": "input_tokens * input_rate + output_tokens * output_rate",
+        "unitName": "token"
+      },
+      "gotchas": [
+        "Free tier available with rate limits",
+        "No standalone billing API for AI Studio — check Google Cloud Console"
+      ],
+      "alternatives": ["anthropic", "openai"],
+      "docsUrl": "https://ai.google.dev/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "voyage-ai": {
+      "id": "voyage-ai",
+      "name": "Voyage AI",
+      "packageNames": ["voyageai"],
+      "envPatterns": ["VOYAGE_API_KEY"],
+      "importPatterns": ["voyageai"],
+      "mentionKeywords": ["voyage", "voyage ai", "voyage-ai"],
+      "billingModel": "token_usage",
+      "scalingShape": "linear",
+      "apiTier": "calc",
+      "pricing": {
+        "formula": "tokens * rate_per_token",
+        "unitName": "token"
+      },
+      "gotchas": [
+        "Embedding-only service — cost scales with document corpus size"
+      ],
+      "alternatives": ["openai embeddings", "cohere embed"],
+      "docsUrl": "https://docs.voyageai.com/docs/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "vercel": {
+      "id": "vercel",
+      "name": "Vercel",
+      "packageNames": ["@vercel/analytics", "@vercel/functions", "@vercel/speed-insights", "@vercel/blob", "@vercel/edge-config"],
+      "envPatterns": ["VERCEL_TOKEN", "VERCEL_ORG_ID", "VERCEL_PROJECT_ID"],
+      "importPatterns": ["@vercel/"],
+      "mentionKeywords": ["vercel", "vercel deploy", "vercel functions"],
+      "billingModel": "compute",
+      "scalingShape": "tiered_jump",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.vercel.com/v2/teams/{teamId}/billing",
+      "pricing": {
+        "formula": "base_plan + function_invocations + bandwidth + edge_requests",
+        "monthlyBase": 20
+      },
+      "gotchas": [
+        "Pro plan is $20/mo base, but overages on functions, bandwidth, and edge requests can spike",
+        "Edge Function pricing differs from Serverless Function pricing",
+        "Image optimization has separate per-image charges"
+      ],
+      "alternatives": ["netlify", "railway", "fly.io"],
+      "docsUrl": "https://vercel.com/docs/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "supabase": {
+      "id": "supabase",
+      "name": "Supabase",
+      "packageNames": ["@supabase/supabase-js", "@supabase/ssr"],
+      "envPatterns": ["SUPABASE_URL", "NEXT_PUBLIC_SUPABASE_URL", "SUPABASE_SERVICE_ROLE_KEY", "NEXT_PUBLIC_SUPABASE_ANON_KEY"],
+      "importPatterns": ["@supabase/supabase-js", "@supabase/ssr"],
+      "mentionKeywords": ["supabase"],
+      "billingModel": "tiered",
+      "scalingShape": "tiered_jump",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.supabase.com/v1/projects/{ref}/usage",
+      "pricing": {
+        "formula": "plan_base + storage_overage + bandwidth_overage + function_invocations",
+        "monthlyBase": 25
+      },
+      "gotchas": [
+        "Storage charges accumulate even when idle",
+        "Database size can grow quickly with unoptimized queries or missing cleanup",
+        "Free tier pauses after 1 week of inactivity"
+      ],
+      "alternatives": ["neon", "planetscale", "firebase"],
+      "docsUrl": "https://supabase.com/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "stripe": {
+      "id": "stripe",
+      "name": "Stripe",
+      "packageNames": ["stripe", "@stripe/stripe-js", "@stripe/react-stripe-js"],
+      "envPatterns": ["STRIPE_SECRET_KEY", "STRIPE_PUBLISHABLE_KEY", "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY", "STRIPE_WEBHOOK_SECRET"],
+      "importPatterns": ["stripe"],
+      "mentionKeywords": ["stripe", "stripe payments", "stripe checkout"],
+      "billingModel": "percentage",
+      "scalingShape": "percentage",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.stripe.com/v1/balance",
+      "pricing": {
+        "formula": "transaction_volume * 0.029 + transaction_count * 0.30",
+        "unitRate": 0.029,
+        "unitName": "transaction"
+      },
+      "gotchas": [
+        "2.9% + $0.30 per successful card charge — this is processing fees, not SaaS cost",
+        "International cards and currency conversion add extra fees",
+        "Disputes (chargebacks) cost $15 each regardless of outcome"
+      ],
+      "docsUrl": "https://stripe.com/pricing",
+      "lastVerified": "2026-03-24",
+      "pricingNotes": "Track as processing fees, not subscription cost"
+    },
+    "scrapfly": {
+      "id": "scrapfly",
+      "name": "Scrapfly",
+      "packageNames": ["scrapfly-sdk", "scrapfly"],
+      "envPatterns": ["SCRAPFLY_KEY", "SCRAPFLY_API_KEY"],
+      "importPatterns": ["scrapfly"],
+      "mentionKeywords": ["scrapfly"],
+      "billingModel": "credit_pool",
+      "scalingShape": "linear_burndown",
+      "apiTier": "live",
+      "apiEndpoint": "https://api.scrapfly.io/account",
+      "pricing": {
+        "formula": "credits_used * credit_usd_rate",
+        "unitRate": 0.00015,
+        "unitName": "credit"
+      },
+      "gotchas": [
+        "Anti-bot bypass options consume 5-25x base credits per request",
+        "JavaScript rendering adds extra credit cost",
+        "Credits reset monthly — unused credits do not roll over"
+      ],
+      "alternatives": ["cheerio", "playwright", "firecrawl"],
+      "docsUrl": "https://scrapfly.io/docs/scrape-api/billing",
+      "lastVerified": "2026-03-24"
+    },
+    "browserbase": {
+      "id": "browserbase",
+      "name": "Browserbase",
+      "packageNames": ["@browserbasehq/sdk", "@browserbasehq/stagehand"],
+      "envPatterns": ["BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID"],
+      "importPatterns": ["@browserbasehq/sdk", "@browserbasehq/stagehand"],
+      "mentionKeywords": ["browserbase", "stagehand"],
+      "billingModel": "per_unit",
+      "scalingShape": "linear",
+      "apiTier": "est",
+      "pricing": {
+        "formula": "sessions * per_session_rate",
+        "unitName": "session"
+      },
+      "gotchas": [
+        "Session duration affects cost — long-running browser sessions burn more",
+        "Concurrent session limits may cause queuing on lower plans"
+      ],
+      "alternatives": ["playwright", "puppeteer"],
+      "docsUrl": "https://docs.browserbase.com/guides/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "upstash": {
+      "id": "upstash",
+      "name": "Upstash Redis",
+      "packageNames": ["@upstash/redis", "@upstash/ratelimit", "@upstash/vector", "@upstash/qstash"],
+      "envPatterns": ["UPSTASH_REDIS_REST_URL", "UPSTASH_REDIS_REST_TOKEN"],
+      "importPatterns": ["@upstash/redis", "@upstash/ratelimit"],
+      "mentionKeywords": ["upstash", "upstash redis"],
+      "billingModel": "per_unit",
+      "scalingShape": "linear",
+      "apiTier": "est",
+      "pricing": {
+        "formula": "commands * per_command_rate",
+        "unitRate": 0.000002,
+        "unitName": "command"
+      },
+      "gotchas": [
+        "Free tier includes 10K commands/day",
+        "Pay-as-you-go is $0.2 per 100K commands after free tier"
+      ],
+      "alternatives": ["redis (self-hosted)", "dragonfly"],
+      "docsUrl": "https://upstash.com/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "resend": {
+      "id": "resend",
+      "name": "Resend",
+      "packageNames": ["resend"],
+      "envPatterns": ["RESEND_API_KEY"],
+      "importPatterns": ["resend"],
+      "mentionKeywords": ["resend"],
+      "billingModel": "per_unit",
+      "scalingShape": "linear",
+      "apiTier": "est",
+      "pricing": {
+        "formula": "emails_sent * per_email_rate",
+        "unitName": "email"
+      },
+      "gotchas": [
+        "Free tier: 100 emails/day, 3000/month",
+        "Pro plan: $20/mo for 50K emails",
+        "Charges per email sent, not per API call"
+      ],
+      "alternatives": ["sendgrid", "postmark", "ses"],
+      "docsUrl": "https://resend.com/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "inngest": {
+      "id": "inngest",
+      "name": "Inngest",
+      "packageNames": ["inngest"],
+      "envPatterns": ["INNGEST_EVENT_KEY", "INNGEST_SIGNING_KEY"],
+      "importPatterns": ["inngest"],
+      "mentionKeywords": ["inngest"],
+      "billingModel": "tiered",
+      "scalingShape": "tiered_jump",
+      "apiTier": "calc",
+      "pricing": {
+        "formula": "plan_base + function_runs_overage",
+        "unitName": "function run"
+      },
+      "gotchas": [
+        "Free tier: 24hr event history, community support",
+        "Cost scales with function step count, not just invocation count"
+      ],
+      "alternatives": ["trigger.dev", "temporal"],
+      "docsUrl": "https://www.inngest.com/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "posthog": {
+      "id": "posthog",
+      "name": "PostHog",
+      "packageNames": ["posthog-js", "posthog-node"],
+      "envPatterns": ["POSTHOG_KEY", "NEXT_PUBLIC_POSTHOG_KEY", "POSTHOG_HOST", "NEXT_PUBLIC_POSTHOG_HOST"],
+      "importPatterns": ["posthog-js", "posthog-node"],
+      "mentionKeywords": ["posthog"],
+      "billingModel": "tiered",
+      "scalingShape": "tiered_jump",
+      "apiTier": "calc",
+      "pricing": {
+        "formula": "events beyond free tier * per_event_rate",
+        "unitName": "event"
+      },
+      "gotchas": [
+        "Free tier: 1M events/month — generous but easy to exceed with high-traffic apps",
+        "Session replay, feature flags, and surveys have separate pricing",
+        "Self-hosted option eliminates hosting cost but requires infrastructure"
+      ],
+      "alternatives": ["mixpanel", "amplitude", "plausible"],
+      "docsUrl": "https://posthog.com/pricing",
+      "lastVerified": "2026-03-24"
+    },
+    "aws": {
+      "id": "aws",
+      "name": "Amazon Web Services",
+      "packageNames": ["@aws-sdk/client-s3", "@aws-sdk/client-ecs", "@aws-sdk/client-ssm", "@aws-sdk/client-lambda", "aws-sdk"],
+      "envPatterns": ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION", "AWS_SESSION_TOKEN"],
+      "importPatterns": ["@aws-sdk/"],
+      "mentionKeywords": ["aws", "amazon web services", "s3", "ecs", "lambda"],
+      "billingModel": "compute",
+      "scalingShape": "linear",
+      "apiTier": "blind",
+      "pricing": {
+        "formula": "Varies by service — S3, ECS, Lambda, etc. each have distinct pricing"
+      },
+      "gotchas": [
+        "AWS Cost Explorer API exists but requires IAM permissions and is itself billed",
+        "Data transfer costs are the most common surprise on AWS bills",
+        "ECS Fargate pricing is per-vCPU-hour and per-GB-hour"
+      ],
+      "alternatives": ["gcp", "azure", "fly.io"],
+      "docsUrl": "https://aws.amazon.com/pricing/",
+      "lastVerified": "2026-03-24",
+      "pricingNotes": "Complex multi-service billing — recommend tracking via AWS Cost Explorer directly"
+    }
+  }
+}

package/skills/setup-burnwatch/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: setup-burnwatch
+description: Guided burnwatch setup — detects paid services in the project and walks through configuring budgets and API keys for each one. Use when the user wants to set up cost tracking, mentions burnwatch setup, or when burnwatch is not yet initialized.
+user-invocable: true
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# /setup-burnwatch — Guided Cost Tracking Setup
+
+Walk the user through setting up burnwatch for their project. This is an interactive, conversational onboarding — not a dump of commands.
+
+## Step 1: Initialize
+
+Check if `.burnwatch/config.json` exists. If not, run:
+
+```bash
+node <path-to-burnwatch>/dist/cli.js init
+```
+
+Present the detected services to the user in a clean summary.
+
+## Step 2: Guided Service Configuration
+
+For each detected service, walk the user through configuration **one service at a time** or in logical groups. Use this priority order:
+
+### High-priority (usage-based, likely to cause surprises):
+1. **LLM providers** (Anthropic, OpenAI, Google Gemini) — these are usually the biggest spend
+2. **Scraping/browser** (Scrapfly, Browserbase) — credit-based, easy to overspend
+3. **Infrastructure** (Vercel, AWS, Supabase) — tiered with overages
+
+### Medium-priority (transaction/event-based):
+4. **Payments** (Stripe) — percentage-based, scales with revenue
+5. **Email** (Resend) — per-email, usually small
+6. **Cache/queue** (Upstash, Inngest) — per-command, usually small
+
+### Low-priority (flat-rate or free tier):
+7. **Analytics** (PostHog) — often on free tier
+8. **Embeddings** (Voyage AI) — usually small volume
+
+For each service, ask the user:
+
+1. **"Do you have a billing/admin API key for [service]?"**
+   - If yes: `burnwatch add <service> --key <KEY> --budget <N>`
+   - If no: explain what tier they'll get (CALC/EST) and that's fine
+
+2. **"What's your monthly budget for [service]?"**
+   - Suggest a reasonable default based on the service type
+   - For flat-rate: "What plan are you on? (e.g., PostHog free tier = $0/mo)"
+
+3. **"Any notes?"** — skip this for most, but for complex services like AWS, acknowledge that burnwatch tracks it as BLIND and suggest they check their AWS console directly.
+
+## Step 3: Show the Brief
+
+After configuring all services, run `burnwatch status` and show the result. Celebrate what's tracked and be honest about what's still BLIND.
+
+## Key Behaviors
+
+- **Be concise.** Don't explain what burnwatch is — the user already chose to set it up.
+- **Group services.** Don't ask 14 questions one at a time. Group similar services: "For your LLM providers (Anthropic, OpenAI) — do you have admin API keys? What monthly budget for each?"
+- **Suggest defaults.** "Most projects budget $50-100/mo for Anthropic. Sound right?"
+- **Skip what's obvious.** If PostHog is on free tier, just say "I'll set PostHog to $0/mo free tier" and move on.
+- **Be honest about BLIND.** "AWS is too complex for automatic tracking — I'll flag it so you see it in the ledger, but check your AWS console for actual spend."
+- **Show the payoff.** End with the brief so they see the value immediately.
+
+## Example Conversation Flow
+
+```
+Agent: I found 11 paid services in your project. Let me walk you through
+       setting up cost tracking for each one. This takes about 2 minutes.
+
+       First, your LLM providers — Anthropic and OpenAI.
+       Do you have admin API keys for either? And what monthly budget
+       feels right? Most projects do $50-150/mo per provider.
+
+User:  I have my anthropic admin key, it's sk-ant-admin-xxx. Budget $100.
+       OpenAI I don't have an admin key. Budget $50.
+
+Agent: Got it.
+       ✅ Anthropic — LIVE tracking, $100/mo budget
+       🔴 OpenAI — no admin key, setting $50 budget (will show as BLIND
+          until you add a key)
+
+       Next, your scraping services — Scrapfly and Browserbase.
+       These are credit-based and the most common source of surprise bills.
+       Do you have API keys? Budget thoughts?
+
+[... continues through all services ...]
+
+Agent: All set! Here's your spend brief:
+       [shows burnwatch status output]
+
+       You're tracking 8 services with real data, 3 are estimated,
+       and AWS is flagged as BLIND. The brief will appear automatically
+       at the start of every Claude Code session.
+```

package/skills/spend/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: spend
+description: Show current burnwatch spend brief for this project. Use when the user asks about costs, spend, budget, or says /spend.
+user-invocable: true
+allowed-tools: Read, Bash, Glob
+argument-hint: "[service]"
+---
+
+# /spend — Show Current Spend Brief
+
+Run the burnwatch status command and present the results to the user.
+
+## Instructions
+
+1. Check if burnwatch is initialized by looking for `.burnwatch/config.json` in the project root
+2. If not initialized, tell the user: "burnwatch isn't set up yet. Want me to run `/setup-burnwatch` to get started?"
+3. If initialized, run: `node <path-to-burnwatch>/dist/cli.js status`
+4. Present the brief output directly — it's already formatted for terminal display
+5. If the user passed a service name as $ARGUMENTS, also read the registry entry for that service and show its gotchas, alternatives, and pricing details
+
+If the user asks about a specific service (e.g., `/spend scrapfly`), also include:
+- Current spend and budget status
+- The service's gotchas from the registry
+- Known alternatives
+- Pricing model and scaling shape