skill-cost-projections

Cost Projections Skill

Overview

Projects remaining workflow cost based on per-phase averages from completed work. Displays cost data in the HUD/statusline and warns when projected totals exceed a configured budget ceiling.

Minimum data requirement: Needs 2+ completed steps before projecting. With fewer than 2 data points, the average is unreliable — display actual spend only and skip projection.

Step 1: Collect Completed Phase Costs

Read cost data from ~/.claude-octopus/metrics/ or from metrics-tracker.sh output. Each completed phase/step should have an associated cost entry.

# Read metrics from the session metrics directory
METRICS_DIR="$HOME/.claude-octopus/metrics"
SESSION_METRICS="$METRICS_DIR/session-$(date +%Y%m%d).jsonl"

# Each line contains: {"phase": "discover", "cost": 0.42, "tokens_in": 12000, "tokens_out": 3400, "timestamp": "..."}
# Sum costs from completed steps
completed_costs=$(jq -s '[.[].cost]' "$SESSION_METRICS")
completed_count=$(jq -s 'length' "$SESSION_METRICS")
total_spent=$(jq -s '[.[].cost] | add' "$SESSION_METRICS")

Data sources (in priority order):

1. ~/.claude-octopus/metrics/session-*.jsonl — structured per-phase cost entries
2. metrics-tracker.sh output — fallback for legacy sessions
3. HUD accumulated cost counters — last resort

If fewer than 2 completed steps are available, display only actual spend:

💰 Spent: $0.42 (1 step complete — need 2+ for projection)

Step 2: Compute Average Cost Per Step

Calculate the mean cost across all completed steps.

avg_cost=$(echo "$total_spent / $completed_count" | bc -l)

Formula:

avg_cost = total_cost / completed_steps

Example: If 3 steps cost $0.30, $0.50, $0.40 → avg = $1.20 / 3 = $0.40/step

Step 3: Project Remaining Cost

Multiply the average cost per step by the number of remaining steps.

remaining_steps=$((total_steps - completed_count))
projected_remaining=$(echo "$avg_cost * $remaining_steps" | bc -l)
projected_total=$(echo "$total_spent + $projected_remaining" | bc -l)