coderplan-tier 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# coderplan-tier
+
+Analyze your Claude Code usage and get a recommendation for the optimal pricing tier.
+
+## Quick Start
+
+```bash
+npx coderplan-tier@latest
+```
+
+## Problem
+
+Developers need guidance on which Claude Code pricing tier best fits their usage patterns. This tool analyzes actual usage data and recommends the most cost-effective plan.
+
+## Tier Overview
+
+| Tier | Monthly Cost | Rate Limits | Best For |
+|------|--------------|-------------|----------|
+| API Only | Pay-per-token | Unlimited | Occasional users (<1 session/week) |
+| Pro | $20/month | ~45 msgs/5hr, 40-80 hrs/week | Regular daily users |
+| Max 5x | $100/month | 5× Pro limits | Heavy users, multiple projects |
+| Max 20x | $200/month | 20× Pro limits | Power users, constant usage |
+
+## How It Works
+
+1. Reads your Claude Code usage data via [ccusage](https://github.com/ryoppippi/ccusage)
+2. Analyzes usage patterns (sessions, tokens, costs, model mix)
+3. Calculates break-even points for each tier
+4. Recommends the tier that minimizes your total cost
+
+## Example Output
+
+```
+╭─────────────────────────────────────────────────────────╮
+│           CoderPlan Tier Recommendation                 │
+╰─────────────────────────────────────────────────────────╯
+
+Your Usage (Last 30 Days)
+   Sessions:        47
+   Active Days:     22/30
+   Total Tokens:    2.4M
+   API Cost:        $67.32
+   Primary Model:   Claude Sonnet (82%), Opus (18%)
+
+Recommendation: Max 5x ($100/month)
+   Confidence: HIGH (consistent daily usage pattern)
+
+   Reasoning:
+   - You use Claude Code 22 days/month (heavy usage)
+   - Current API costs ($67/mo) exceed Pro break-even (~$30)
+   - Max 5x limits would cover your typical usage
+
+   Projected Savings: ~$47/month vs API-only
+
+╭─────────────────────────────────────────────────────────╮
+│ Tier Comparison                                         │
+├─────────────────────────────────────────────────────────┤
+│ API Only      $67/month  (current spend)                │
+│ Pro           $35/month  ($20 + ~$15 overflow)          │
+│ Max 5x        $100/month (no overflow expected)  <--    │
+│ Max 20x       $200/month (overkill)                     │
+╰─────────────────────────────────────────────────────────╯
+```
+
+## CLI Options
+
+```bash
+coderplan-tier                # Analyze last 30 days (default)
+coderplan-tier --period 90    # Analyze last 90 days
+coderplan-tier --json         # Output as JSON
+coderplan-tier --verbose      # Show detailed metrics
+```
+
+## Break-Even Analysis
+
+The recommendation algorithm considers:
+
+| Tier | Break-Even Point |
+|------|------------------|
+| Pro ($20) | ~$25-30/month API spend |
+| Max 5x ($100) | ~$120-150/month API spend |
+| Max 20x ($200) | ~$250+/month API spend |
+
+## Confidence Levels
+
+The tool shows a confidence indicator based on usage variance:
+
+- **HIGH**: Consistent daily usage, stable patterns
+- **MEDIUM**: Some variation but clear trend
+- **LOW**: Highly variable (heavy some weeks, idle others)
+
+## API Token Pricing Reference
+
+| Model | Input (per 1M) | Output (per 1M) |
+|-------|----------------|-----------------|
+| Haiku | $1 | $5 |
+| Sonnet 4.5 | $3 | $15 |
+| Opus 4.5 | $5 | $25 |
+| Opus 4.1 | $15 | $75 |
+
+## Requirements
+
+- Node.js 18+
+- Claude Code usage history (stored locally by Claude Code)
+
+## License
+
+MIT

package/dist/collector.d.ts

@@ -0,0 +1,2 @@
+import type { UsageData } from "./types.js";
+export declare function getUsageData(days: number): Promise<UsageData>;

package/dist/collector.js

@@ -0,0 +1,101 @@
+import { execSync } from "child_process";
+export async function getUsageData(days) {
+    const since = formatDateYYYYMMDD(new Date(Date.now() - days * 24 * 60 * 60 * 1000));
+    // Get daily data (more granular for active days calculation)
+    const dailyData = runCcusage("daily", since);
+    // Aggregate totals from daily data
+    let totalCost = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCacheCreationTokens = 0;
+    let totalCacheReadTokens = 0;
+    const modelMap = new Map();
+    for (const day of dailyData.daily) {
+        totalCost += day.totalCost;
+        totalInputTokens += day.inputTokens;
+        totalOutputTokens += day.outputTokens;
+        totalCacheCreationTokens += day.cacheCreationTokens;
+        totalCacheReadTokens += day.cacheReadTokens;
+        // Aggregate model usage
+        for (const model of day.modelBreakdowns) {
+            const existing = modelMap.get(model.modelName);
+            if (existing) {
+                existing.cost += model.cost;
+                existing.inputTokens += model.inputTokens;
+                existing.outputTokens += model.outputTokens;
+            }
+            else {
+                modelMap.set(model.modelName, {
+                    model: model.modelName,
+                    cost: model.cost,
+                    inputTokens: model.inputTokens,
+                    outputTokens: model.outputTokens,
+                    percentage: 0,
+                });
+            }
+        }
+    }
+    const activeDays = dailyData.daily.filter((d) => d.totalCost > 0).length;
+    const sessionCount = dailyData.daily.length; // Approximation: 1 session per active day
+    // Calculate percentages
+    const modelBreakdown = Array.from(modelMap.values()).map((m) => ({
+        ...m,
+        percentage: totalCost > 0 ? (m.cost / totalCost) * 100 : 0,
+    }));
+    // Sort by cost descending
+    modelBreakdown.sort((a, b) => b.cost - a.cost);
+    const dailyUsage = dailyData.daily.map((d) => ({
+        date: d.date,
+        cost: d.totalCost,
+        sessions: 1,
+    }));
+    return {
+        totalCost,
+        totalInputTokens,
+        totalOutputTokens,
+        totalCacheCreationTokens,
+        totalCacheReadTokens,
+        sessionCount,
+        activeDays,
+        periodDays: days,
+        modelBreakdown,
+        dailyUsage,
+    };
+}
+function runCcusage(command, since) {
+    try {
+        const output = execSync(`npx ccusage@latest ${command} --json --since ${since}`, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 30000,
+        });
+        return JSON.parse(output);
+    }
+    catch (error) {
+        if (error instanceof Error && "stdout" in error) {
+            const stdout = error.stdout;
+            // ccusage may return empty data with exit code 0
+            if (stdout) {
+                try {
+                    return JSON.parse(stdout);
+                }
+                catch {
+                    // Fall through to error handling
+                }
+            }
+        }
+        // Return empty data structure for no data case
+        if (error instanceof Error &&
+            (error.message.includes("No usage data") ||
+                error.message.includes("ENOENT"))) {
+            return { monthly: [], daily: [] };
+        }
+        throw new Error(`Failed to run ccusage: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function formatDateYYYYMMDD(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const day = String(date.getDate()).padStart(2, "0");
+    return `${year}${month}${day}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import { getUsageData } from "./collector.js";
+import { recommend } from "./recommender.js";
+import { renderRecommendation, renderJson } from "./renderer.js";
+program
+    .name("coderplan-tier")
+    .description("Analyze Claude Code usage and get tier recommendations")
+    .version("0.1.0")
+    .option("-p, --period <days>", "Analysis period in days", "30")
+    .option("-j, --json", "Output as JSON")
+    .option("-v, --verbose", "Show detailed metrics")
+    .action(async (options) => {
+    const days = parseInt(options.period, 10);
+    if (isNaN(days) || days < 1 || days > 365) {
+        console.error("Error: Period must be between 1 and 365 days");
+        process.exit(1);
+    }
+    try {
+        const usage = await getUsageData(days);
+        if (usage.totalCost === 0 && usage.sessionCount === 0) {
+            console.log("No Claude Code usage data found for the specified period.");
+            console.log("Make sure you have used Claude Code and ccusage can access your data.");
+            process.exit(0);
+        }
+        const recommendation = recommend(usage);
+        if (options.json) {
+            console.log(renderJson(usage, recommendation));
+        }
+        else {
+            console.log(renderRecommendation(usage, recommendation, options.verbose));
+        }
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/recommender.d.ts

@@ -0,0 +1,2 @@
+import type { UsageData, Recommendation } from "./types.js";
+export declare function recommend(usage: UsageData): Recommendation;

package/dist/recommender.js

@@ -0,0 +1,132 @@
+// Tier subscription costs
+const TIER_COSTS = {
+    "API Only": 0,
+    Pro: 20,
+    "Max 5x": 100,
+    "Max 20x": 200,
+};
+// Approximate break-even points (API cost at which tier becomes worthwhile)
+const BREAK_EVEN = {
+    "API Only": 0,
+    Pro: 25,
+    "Max 5x": 120,
+    "Max 20x": 250,
+};
+// Approximate coverage ratios (what % of usage is covered by subscription)
+// These are estimates based on typical usage patterns
+const COVERAGE_RATIO = {
+    "API Only": 0,
+    Pro: 0.7, // Pro covers ~70% of moderate usage
+    "Max 5x": 0.9, // Max 5x covers ~90% of heavy usage
+    "Max 20x": 0.98, // Max 20x covers nearly all usage
+};
+export function recommend(usage) {
+    const monthlyMultiplier = 30 / usage.periodDays;
+    const currentMonthlyCost = usage.totalCost * monthlyMultiplier;
+    const activeDaysPerMonth = usage.activeDays * monthlyMultiplier;
+    // Calculate projected costs for each tier
+    const projectedCosts = calculateTierCosts(currentMonthlyCost);
+    // Select tier with lowest total cost
+    const tier = selectLowestCostTier(projectedCosts);
+    // Calculate confidence
+    const confidence = calculateConfidence(usage);
+    // Generate reasons
+    const reasons = generateReasons(tier, currentMonthlyCost, activeDaysPerMonth, usage);
+    // Mark recommended tier
+    for (const cost of projectedCosts) {
+        cost.isRecommended = cost.tier === tier;
+    }
+    // Calculate savings vs API-only
+    const apiOnlyCost = projectedCosts.find((c) => c.tier === "API Only")?.monthlyCost ?? currentMonthlyCost;
+    const recommendedCost = projectedCosts.find((c) => c.tier === tier)?.monthlyCost ?? currentMonthlyCost;
+    const savings = apiOnlyCost - recommendedCost;
+    return {
+        tier,
+        confidence,
+        reasons,
+        projectedCosts,
+        currentMonthlyCost,
+        savings: Math.max(0, savings),
+    };
+}
+function selectLowestCostTier(projectedCosts) {
+    // Find tier with minimum total cost
+    let minCost = Infinity;
+    let bestTier = "API Only";
+    for (const cost of projectedCosts) {
+        if (cost.monthlyCost < minCost) {
+            minCost = cost.monthlyCost;
+            bestTier = cost.tier;
+        }
+    }
+    return bestTier;
+}
+function calculateTierCosts(currentMonthlyCost) {
+    return ["API Only", "Pro", "Max 5x", "Max 20x"].map((tier) => {
+        const subscriptionCost = TIER_COSTS[tier];
+        const coverage = COVERAGE_RATIO[tier];
+        // Overflow = portion of usage not covered by subscription
+        const overflowCost = tier === "API Only"
+            ? currentMonthlyCost
+            : Math.max(0, currentMonthlyCost * (1 - coverage));
+        return {
+            tier,
+            subscriptionCost,
+            overflowCost: Math.round(overflowCost * 100) / 100,
+            monthlyCost: Math.round((subscriptionCost + overflowCost) * 100) / 100,
+            isRecommended: false,
+        };
+    });
+}
+function calculateConfidence(usage) {
+    if (usage.dailyUsage.length < 7) {
+        return "LOW"; // Not enough data
+    }
+    // Calculate coefficient of variation for daily costs
+    const costs = usage.dailyUsage.map((d) => d.cost);
+    const mean = costs.reduce((a, b) => a + b, 0) / costs.length;
+    if (mean === 0) {
+        return "LOW";
+    }
+    const variance = costs.reduce((sum, c) => sum + Math.pow(c - mean, 2), 0) / costs.length;
+    const stdDev = Math.sqrt(variance);
+    const cv = stdDev / mean;
+    // CV thresholds for confidence
+    if (cv < 0.5)
+        return "HIGH";
+    if (cv < 1.0)
+        return "MEDIUM";
+    return "LOW";
+}
+function generateReasons(tier, monthlyCost, activeDays, usage) {
+    const reasons = [];
+    // Usage frequency reason
+    if (activeDays < 5) {
+        reasons.push(`Light usage (${Math.round(activeDays)} active days/month)`);
+    }
+    else if (activeDays < 15) {
+        reasons.push(`Moderate usage (${Math.round(activeDays)} active days/month)`);
+    }
+    else {
+        reasons.push(`Heavy usage (${Math.round(activeDays)} active days/month)`);
+    }
+    // Cost-based reason
+    const breakEven = BREAK_EVEN[tier];
+    if (tier === "API Only") {
+        reasons.push(`API costs ($${monthlyCost.toFixed(0)}/mo) below subscription value`);
+    }
+    else if (monthlyCost > breakEven) {
+        reasons.push(`API costs ($${monthlyCost.toFixed(0)}/mo) exceed ${tier} break-even (~$${breakEven})`);
+    }
+    else {
+        reasons.push(`${tier} provides buffer for usage growth`);
+    }
+    // Model mix reason
+    const opusUsage = usage.modelBreakdown
+        .filter((m) => m.model.toLowerCase().includes("opus"))
+        .reduce((sum, m) => sum + m.percentage, 0);
+    if (opusUsage > 30) {
+        reasons.push(`High Opus usage (${opusUsage.toFixed(0)}%) benefits from subscription`);
+    }
+    return reasons;
+}

package/dist/renderer.d.ts

@@ -0,0 +1,3 @@
+import type { UsageData, Recommendation } from "./types.js";
+export declare function renderRecommendation(usage: UsageData, rec: Recommendation, verbose: boolean): string;
+export declare function renderJson(usage: UsageData, rec: Recommendation): string;

package/dist/renderer.js

@@ -0,0 +1,189 @@
+import pc from "picocolors";
+const BOX_WIDTH = 58;
+export function renderRecommendation(usage, rec, verbose) {
+    const lines = [];
+    // Header
+    lines.push(boxTop());
+    lines.push(boxMiddle(pc.bold("CoderPlan Tier Recommendation")));
+    lines.push(boxBottom());
+    lines.push("");
+    // Usage summary
+    lines.push(pc.bold("Your Usage") + pc.dim(` (Last ${usage.periodDays} Days)`));
+    lines.push(`   Sessions:        ${usage.sessionCount}`);
+    lines.push(`   Active Days:     ${usage.activeDays}/${usage.periodDays}`);
+    lines.push(`   Total Tokens:    ${formatTokens(usage.totalInputTokens + usage.totalOutputTokens)}`);
+    lines.push(`   API Cost:        $${usage.totalCost.toFixed(2)}`);
+    // Model breakdown
+    if (usage.modelBreakdown.length > 0) {
+        const modelStr = usage.modelBreakdown
+            .slice(0, 3)
+            .map((m) => `${simplifyModelName(m.model)} (${m.percentage.toFixed(0)}%)`)
+            .join(", ");
+        lines.push(`   Primary Model:   ${modelStr}`);
+    }
+    lines.push("");
+    // Recommendation
+    const tierColor = getTierColor(rec.tier);
+    lines.push(pc.bold("Recommendation: ") + tierColor(rec.tier) + pc.dim(` ($${getTierCost(rec.tier)}/month)`));
+    const confColor = getConfidenceColor(rec.confidence);
+    lines.push(`   Confidence: ${confColor(rec.confidence)} ${pc.dim(getConfidenceNote(rec.confidence))}`);
+    lines.push("");
+    lines.push("   Reasoning:");
+    for (const reason of rec.reasons) {
+        lines.push(`   ${pc.dim("-")} ${reason}`);
+    }
+    if (rec.savings > 0) {
+        lines.push("");
+        lines.push(`   Projected Savings: ${pc.green(`~$${rec.savings.toFixed(0)}/month`)} vs API-only`);
+    }
+    lines.push("");
+    // Tier comparison table
+    lines.push(boxTop());
+    lines.push(boxMiddle("Tier Comparison"));
+    lines.push(boxSeparator());
+    for (const cost of rec.projectedCosts) {
+        const marker = cost.isRecommended ? pc.cyan(" <--") : "";
+        const costStr = `$${cost.monthlyCost.toFixed(0)}/month`;
+        const detail = cost.tier === "API Only"
+            ? "(current spend)"
+            : cost.overflowCost > 0
+                ? `($${cost.subscriptionCost} + ~$${cost.overflowCost.toFixed(0)} overflow)`
+                : "(no overflow expected)";
+        const line = `${padRight(cost.tier, 12)} ${padRight(costStr, 12)} ${pc.dim(detail)}${marker}`;
+        lines.push(boxContent(line));
+    }
+    lines.push(boxBottom());
+    // Verbose: show detailed metrics
+    if (verbose) {
+        lines.push("");
+        lines.push(pc.bold("Detailed Metrics"));
+        lines.push(`   Input Tokens:    ${formatTokens(usage.totalInputTokens)}`);
+        lines.push(`   Output Tokens:   ${formatTokens(usage.totalOutputTokens)}`);
+        lines.push(`   Cache Creation:  ${formatTokens(usage.totalCacheCreationTokens)}`);
+        lines.push(`   Cache Read:      ${formatTokens(usage.totalCacheReadTokens)}`);
+        lines.push("");
+        lines.push(pc.bold("Model Breakdown"));
+        for (const model of usage.modelBreakdown) {
+            lines.push(`   ${padRight(simplifyModelName(model.model), 20)} $${model.cost.toFixed(2)} (${model.percentage.toFixed(1)}%)`);
+        }
+    }
+    return lines.join("\n");
+}
+export function renderJson(usage, rec) {
+    return JSON.stringify({
+        usage: {
+            periodDays: usage.periodDays,
+            activeDays: usage.activeDays,
+            sessionCount: usage.sessionCount,
+            totalCost: usage.totalCost,
+            totalTokens: usage.totalInputTokens + usage.totalOutputTokens,
+            modelBreakdown: usage.modelBreakdown,
+        },
+        recommendation: {
+            tier: rec.tier,
+            confidence: rec.confidence,
+            reasons: rec.reasons,
+            currentMonthlyCost: rec.currentMonthlyCost,
+            projectedSavings: rec.savings,
+            tierCosts: rec.projectedCosts,
+        },
+    }, null, 2);
+}
+// Box drawing helpers
+function boxTop() {
+    return pc.dim("╭" + "─".repeat(BOX_WIDTH) + "╮");
+}
+function boxBottom() {
+    return pc.dim("╰" + "─".repeat(BOX_WIDTH) + "╯");
+}
+function boxSeparator() {
+    return pc.dim("├" + "─".repeat(BOX_WIDTH) + "┤");
+}
+function boxMiddle(text) {
+    const stripped = stripAnsi(text);
+    const padding = Math.max(0, BOX_WIDTH - stripped.length);
+    const left = Math.floor(padding / 2);
+    const right = padding - left;
+    return pc.dim("│") + " ".repeat(left) + text + " ".repeat(right) + pc.dim("│");
+}
+function boxContent(text) {
+    const stripped = stripAnsi(text);
+    const padding = Math.max(0, BOX_WIDTH - stripped.length - 1);
+    return pc.dim("│") + " " + text + " ".repeat(padding) + pc.dim("│");
+}
+function stripAnsi(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1b\[[0-9;]*m/g, "");
+}
+function padRight(str, len) {
+    return str + " ".repeat(Math.max(0, len - str.length));
+}
+function formatTokens(tokens) {
+    if (tokens >= 1_000_000) {
+        return `${(tokens / 1_000_000).toFixed(1)}M`;
+    }
+    if (tokens >= 1_000) {
+        return `${(tokens / 1_000).toFixed(1)}K`;
+    }
+    return tokens.toString();
+}
+function simplifyModelName(model) {
+    const lower = model.toLowerCase();
+    if (lower.includes("opus"))
+        return "Opus";
+    if (lower.includes("sonnet"))
+        return "Sonnet";
+    if (lower.includes("haiku"))
+        return "Haiku";
+    return model.split("-").slice(0, 2).join(" ");
+}
+function getTierColor(tier) {
+    switch (tier) {
+        case "API Only":
+            return pc.dim;
+        case "Pro":
+            return pc.blue;
+        case "Max 5x":
+            return pc.cyan;
+        case "Max 20x":
+            return pc.magenta;
+        default:
+            return (s) => s;
+    }
+}
+function getTierCost(tier) {
+    switch (tier) {
+        case "Pro":
+            return 20;
+        case "Max 5x":
+            return 100;
+        case "Max 20x":
+            return 200;
+        default:
+            return 0;
+    }
+}
+function getConfidenceColor(confidence) {
+    switch (confidence) {
+        case "HIGH":
+            return pc.green;
+        case "MEDIUM":
+            return pc.yellow;
+        case "LOW":
+            return pc.red;
+        default:
+            return (s) => s;
+    }
+}
+function getConfidenceNote(confidence) {
+    switch (confidence) {
+        case "HIGH":
+            return "(consistent usage pattern)";
+        case "MEDIUM":
+            return "(some variation in usage)";
+        case "LOW":
+            return "(highly variable usage)";
+        default:
+            return "";
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+export interface UsageData {
+    totalCost: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheCreationTokens: number;
+    totalCacheReadTokens: number;
+    sessionCount: number;
+    activeDays: number;
+    periodDays: number;
+    modelBreakdown: ModelUsage[];
+    dailyUsage: DailyUsage[];
+}
+export interface ModelUsage {
+    model: string;
+    cost: number;
+    inputTokens: number;
+    outputTokens: number;
+    percentage: number;
+}
+export interface DailyUsage {
+    date: string;
+    cost: number;
+    sessions: number;
+}
+export type Tier = "API Only" | "Pro" | "Max 5x" | "Max 20x";
+export type Confidence = "HIGH" | "MEDIUM" | "LOW";
+export interface Recommendation {
+    tier: Tier;
+    confidence: Confidence;
+    reasons: string[];
+    projectedCosts: TierCost[];
+    currentMonthlyCost: number;
+    savings: number;
+}
+export interface TierCost {
+    tier: Tier;
+    monthlyCost: number;
+    subscriptionCost: number;
+    overflowCost: number;
+    isRecommended: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "coderplan-tier",
+  "version": "0.1.0",
+  "description": "Analyze Claude Code usage and get tier recommendations",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "coderplan-tier": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "usage",
+    "pricing",
+    "tier"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "picocolors": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}