coderplan-tier 0.1.0 → 0.3.0

package/README.md

@@ -23,43 +23,49 @@ Developers need guidance on which Claude Code pricing tier best fits their 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)
+1. Reads usage data from both:
+   - **Claude Code** via [ccusage](https://github.com/ryoppippi/ccusage)
+   - **OpenAI Codex** via [@ccusage/codex](https://www.npmjs.com/package/@ccusage/codex)
+2. Combines and 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
 
+This is especially useful for developers transitioning from Codex to Claude - see your combined costs and what Claude tier would cover your usage.
+
 ## Example Output
 
 ```
-╭─────────────────────────────────────────────────────────╮
-│           CoderPlan Tier Recommendation                 │
-╰─────────────────────────────────────────────────────────╯
+╭──────────────────────────────────────────────────────────╮
+│              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%)
+   API Cost:        $127.32
+   ├─ Claude:     $67.32 (53%)
+   └─ Codex:      $60.00 (47%)
+   Primary Model:   Claude Opus (45%), Codex gpt-5 (40%), Claude Sonnet (15%)
 
 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)
+   - Heavy usage (22 active days/month)
+   - API costs ($127/mo) exceed Pro break-even (~$25)
    - Max 5x limits would cover your typical usage
 
-   Projected Savings: ~$47/month vs API-only
+   Projected Savings: ~$65/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)                     │
-╰─────────────────────────────────────────────────────────╯
+╭──────────────────────────────────────────────────────────╮
+│ Tier Comparison                                          │
+├──────────────────────────────────────────────────────────┤
+│ API Only     $127/month   (current spend)                │
+│ Pro          $58/month    ($20 + ~$38 overflow)          │
+│ Max 5x       $113/month   ($100 + ~$13 overflow) <--     │
+│ Max 20x      $203/month   ($200 + ~$3 overflow)          │
+╰──────────────────────────────────────────────────────────╯
 ```
 
 ## CLI Options

package/dist/collector.js

@@ -1,32 +1,49 @@
 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
+    // Fetch both Claude and Codex usage in parallel
+    const [claudeData, codexData] = await Promise.all([
+        fetchClaudeUsage(since),
+        fetchCodexUsage(since),
+    ]);
+    // Aggregate totals
     let totalCost = 0;
     let totalInputTokens = 0;
     let totalOutputTokens = 0;
     let totalCacheCreationTokens = 0;
     let totalCacheReadTokens = 0;
+    let claudeCost = 0;
+    let codexCost = 0;
     const modelMap = new Map();
-    for (const day of dailyData.daily) {
+    const dailyMap = new Map();
+    // Process Claude data
+    for (const day of claudeData.daily) {
         totalCost += day.totalCost;
+        claudeCost += day.totalCost;
         totalInputTokens += day.inputTokens;
         totalOutputTokens += day.outputTokens;
-        totalCacheCreationTokens += day.cacheCreationTokens;
-        totalCacheReadTokens += day.cacheReadTokens;
+        totalCacheCreationTokens += day.cacheCreationTokens ?? 0;
+        totalCacheReadTokens += day.cacheReadTokens ?? 0;
+        // Track daily usage
+        const existing = dailyMap.get(day.date);
+        if (existing) {
+            existing.cost += day.totalCost;
+        }
+        else {
+            dailyMap.set(day.date, { date: day.date, cost: day.totalCost, sessions: 1 });
+        }
         // 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;
+        for (const model of day.modelBreakdowns ?? []) {
+            const modelName = `Claude ${simplifyModelName(model.modelName)}`;
+            const existingModel = modelMap.get(modelName);
+            if (existingModel) {
+                existingModel.cost += model.cost;
+                existingModel.inputTokens += model.inputTokens;
+                existingModel.outputTokens += model.outputTokens;
             }
             else {
-                modelMap.set(model.modelName, {
-                    model: model.modelName,
+                modelMap.set(modelName, {
+                    model: modelName,
                     cost: model.cost,
                     inputTokens: model.inputTokens,
                     outputTokens: model.outputTokens,
@@ -35,8 +52,49 @@ export async function getUsageData(days) {
             }
         }
     }
-    const activeDays = dailyData.daily.filter((d) => d.totalCost > 0).length;
-    const sessionCount = dailyData.daily.length; // Approximation: 1 session per active day
+    // Process Codex data
+    for (const day of codexData.daily) {
+        const dayCost = day.costUSD ?? 0;
+        totalCost += dayCost;
+        codexCost += dayCost;
+        totalInputTokens += day.inputTokens;
+        totalOutputTokens += day.outputTokens;
+        // Track daily usage
+        const existing = dailyMap.get(day.date);
+        if (existing) {
+            existing.cost += dayCost;
+        }
+        else {
+            dailyMap.set(day.date, { date: day.date, cost: dayCost, sessions: 1 });
+        }
+        // Aggregate model usage from models object
+        if (day.models) {
+            for (const [modelName, modelData] of Object.entries(day.models)) {
+                const displayName = `Codex ${modelName}`;
+                const existingModel = modelMap.get(displayName);
+                // Estimate cost per model proportionally
+                const modelTokens = modelData.inputTokens + modelData.outputTokens;
+                const dayTotalTokens = day.inputTokens + day.outputTokens;
+                const modelCost = dayTotalTokens > 0 ? (modelTokens / dayTotalTokens) * dayCost : 0;
+                if (existingModel) {
+                    existingModel.cost += modelCost;
+                    existingModel.inputTokens += modelData.inputTokens;
+                    existingModel.outputTokens += modelData.outputTokens;
+                }
+                else {
+                    modelMap.set(displayName, {
+                        model: displayName,
+                        cost: modelCost,
+                        inputTokens: modelData.inputTokens,
+                        outputTokens: modelData.outputTokens,
+                        percentage: 0,
+                    });
+                }
+            }
+        }
+    }
+    const activeDays = Array.from(dailyMap.values()).filter((d) => d.cost > 0).length;
+    const sessionCount = dailyMap.size;
     // Calculate percentages
     const modelBreakdown = Array.from(modelMap.values()).map((m) => ({
         ...m,
@@ -44,11 +102,7 @@ export async function getUsageData(days) {
     }));
     // 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,
-    }));
+    const dailyUsage = Array.from(dailyMap.values()).sort((a, b) => a.date.localeCompare(b.date));
     return {
         totalCost,
         totalInputTokens,
@@ -60,37 +114,40 @@ export async function getUsageData(days) {
         periodDays: days,
         modelBreakdown,
         dailyUsage,
+        claudeCost,
+        codexCost,
     };
 }
-function runCcusage(command, since) {
+async function fetchClaudeUsage(since) {
+    return runCommand(`npx ccusage@latest daily --json --since ${since}`, { daily: [] });
+}
+async function fetchCodexUsage(since) {
+    return runCommand(`npx @ccusage/codex@latest daily --json --since ${since}`, { daily: [] });
+}
+function runCommand(command, fallback) {
     try {
-        const output = execSync(`npx ccusage@latest ${command} --json --since ${since}`, {
+        const output = execSync(command, {
             encoding: "utf-8",
             stdio: ["pipe", "pipe", "pipe"],
-            timeout: 30000,
+            timeout: 60000,
         });
         return JSON.parse(output);
     }
     catch (error) {
+        // Try to parse stdout even on error (some tools exit non-zero with valid output)
         if (error instanceof Error && "stdout" in error) {
             const stdout = error.stdout;
-            // ccusage may return empty data with exit code 0
-            if (stdout) {
+            if (stdout?.trim()) {
                 try {
                     return JSON.parse(stdout);
                 }
                 catch {
-                    // Fall through to error handling
+                    // Fall through
                 }
             }
         }
-        // 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)}`);
+        // Return fallback for missing data
+        return fallback;
     }
 }
 function formatDateYYYYMMDD(date) {
@@ -99,3 +156,13 @@ function formatDateYYYYMMDD(date) {
     const day = String(date.getDate()).padStart(2, "0");
     return `${year}${month}${day}`;
 }
+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(" ");
+}

package/dist/recommender.js

@@ -40,6 +40,8 @@ export function recommend(usage) {
     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;
+    // Generate explanation comparing recommended tier to next tier up
+    const explanation = generateExplanation(tier, projectedCosts);
     return {
         tier,
         confidence,
@@ -47,6 +49,7 @@ export function recommend(usage) {
         projectedCosts,
         currentMonthlyCost,
         savings: Math.max(0, savings),
+        explanation,
     };
 }
 function selectLowestCostTier(projectedCosts) {
@@ -130,3 +133,44 @@ function generateReasons(tier, monthlyCost, activeDays, usage) {
     }
     return reasons;
 }
+const TIER_ORDER = ["API Only", "Pro", "Max 5x", "Max 20x"];
+function generateExplanation(recommendedTier, projectedCosts) {
+    const recommendedIdx = TIER_ORDER.indexOf(recommendedTier);
+    const recommendedCost = projectedCosts.find((c) => c.tier === recommendedTier);
+    if (!recommendedCost)
+        return null;
+    // Compare to next tier up (or down if at max)
+    let comparedTier;
+    if (recommendedIdx < TIER_ORDER.length - 1) {
+        comparedTier = TIER_ORDER[recommendedIdx + 1];
+    }
+    else {
+        comparedTier = TIER_ORDER[recommendedIdx - 1];
+    }
+    const comparedCost = projectedCosts.find((c) => c.tier === comparedTier);
+    if (!comparedCost)
+        return null;
+    const subscriptionDiff = comparedCost.subscriptionCost - recommendedCost.subscriptionCost;
+    const overflowDiff = recommendedCost.overflowCost - comparedCost.overflowCost;
+    // Calculate break-even point
+    // At break-even: recSub + recOverflow(x) = compSub + compOverflow(x)
+    // recSub + x*(1-recCoverage) = compSub + x*(1-compCoverage)
+    // x*(compCoverage - recCoverage) = compSub - recSub
+    // x = (compSub - recSub) / (compCoverage - recCoverage)
+    const recCoverage = COVERAGE_RATIO[recommendedTier];
+    const compCoverage = COVERAGE_RATIO[comparedTier];
+    const coverageDiff = compCoverage - recCoverage;
+    let breakEvenCost = 0;
+    if (coverageDiff > 0) {
+        breakEvenCost = Math.round(subscriptionDiff / coverageDiff);
+    }
+    return {
+        recommendedTier,
+        comparedTier,
+        recommendedCost,
+        comparedCost,
+        subscriptionDiff,
+        overflowDiff,
+        breakEvenCost,
+    };
+}

package/dist/renderer.js

@@ -13,6 +13,14 @@ export function renderRecommendation(usage, rec, verbose) {
     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)}`);
+    // Show Claude/Codex breakdown if both have usage
+    if (usage.claudeCost > 0 && usage.codexCost > 0) {
+        lines.push(`   ${pc.dim("├─")} Claude:     $${usage.claudeCost.toFixed(2)} (${((usage.claudeCost / usage.totalCost) * 100).toFixed(0)}%)`);
+        lines.push(`   ${pc.dim("└─")} Codex:      $${usage.codexCost.toFixed(2)} (${((usage.codexCost / usage.totalCost) * 100).toFixed(0)}%)`);
+    }
+    else if (usage.codexCost > 0) {
+        lines.push(`   ${pc.dim("└─")} Codex only`);
+    }
     // Model breakdown
     if (usage.modelBreakdown.length > 0) {
         const modelStr = usage.modelBreakdown
@@ -53,6 +61,11 @@ export function renderRecommendation(usage, rec, verbose) {
         lines.push(boxContent(line));
     }
     lines.push(boxBottom());
+    // Why this tier? explanation
+    if (rec.explanation) {
+        lines.push("");
+        lines.push(...renderExplanation(rec.explanation));
+    }
     // Verbose: show detailed metrics
     if (verbose) {
         lines.push("");
@@ -76,6 +89,8 @@ export function renderJson(usage, rec) {
             activeDays: usage.activeDays,
             sessionCount: usage.sessionCount,
             totalCost: usage.totalCost,
+            claudeCost: usage.claudeCost,
+            codexCost: usage.codexCost,
             totalTokens: usage.totalInputTokens + usage.totalOutputTokens,
             modelBreakdown: usage.modelBreakdown,
         },
@@ -86,9 +101,29 @@ export function renderJson(usage, rec) {
             currentMonthlyCost: rec.currentMonthlyCost,
             projectedSavings: rec.savings,
             tierCosts: rec.projectedCosts,
+            explanation: rec.explanation,
         },
     }, null, 2);
 }
+function renderExplanation(exp) {
+    const lines = [];
+    const rec = exp.recommendedCost;
+    const comp = exp.comparedCost;
+    lines.push(pc.bold(`Why ${exp.recommendedTier} over ${exp.comparedTier}?`));
+    lines.push(`   ${padRight(exp.recommendedTier + ":", 10)} $${rec.subscriptionCost} subscription + $${rec.overflowCost.toFixed(0)} overflow = ${pc.green(`$${rec.monthlyCost.toFixed(0)} total`)}`);
+    lines.push(`   ${padRight(exp.comparedTier + ":", 10)} $${comp.subscriptionCost} subscription + $${comp.overflowCost.toFixed(0)} overflow = ${pc.dim(`$${comp.monthlyCost.toFixed(0)} total`)}`);
+    lines.push("");
+    if (exp.subscriptionDiff > 0 && exp.overflowDiff > 0) {
+        lines.push(`   The $${exp.subscriptionDiff} subscription difference outweighs the $${exp.overflowDiff.toFixed(0)} overflow savings.`);
+    }
+    else if (exp.subscriptionDiff < 0) {
+        lines.push(`   Lower subscription ($${Math.abs(exp.subscriptionDiff)} less) with acceptable overflow.`);
+    }
+    if (exp.breakEvenCost > 0) {
+        lines.push(`   ${pc.dim(`${exp.comparedTier} becomes better when API costs reach ~$${exp.breakEvenCost}/month.`)}`);
+    }
+    return lines;
+}
 // Box drawing helpers
 function boxTop() {
     return pc.dim("╭" + "─".repeat(BOX_WIDTH) + "╮");
@@ -128,14 +163,13 @@ function formatTokens(tokens) {
     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(" ");
+    // Model names already have "Claude" or "Codex" prefix from collector
+    // Just clean up for display
+    return model
+        .replace("claude-", "")
+        .replace("-20251101", "")
+        .replace("-20251001", "")
+        .replace("-20250929", "");
 }
 function getTierColor(tier) {
     switch (tier) {

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export interface UsageData {
     periodDays: number;
     modelBreakdown: ModelUsage[];
     dailyUsage: DailyUsage[];
+    claudeCost: number;
+    codexCost: number;
 }
 export interface ModelUsage {
     model: string;
@@ -31,6 +33,16 @@ export interface Recommendation {
     projectedCosts: TierCost[];
     currentMonthlyCost: number;
     savings: number;
+    explanation: TierExplanation | null;
+}
+export interface TierExplanation {
+    recommendedTier: Tier;
+    comparedTier: Tier;
+    recommendedCost: TierCost;
+    comparedCost: TierCost;
+    subscriptionDiff: number;
+    overflowDiff: number;
+    breakEvenCost: number;
 }
 export interface TierCost {
     tier: Tier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderplan-tier",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Analyze Claude Code usage and get tier recommendations",
   "type": "module",
   "main": "dist/index.js",