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 USD (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 USD, 0.50 USD, 0.40 USD → avg = 1.20 USD / 3 = 0.40 USD/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)

Formula:

projected_remaining = avg_cost × remaining_steps
projected_total     = total_spent + projected_remaining

Step counts by workflow type:

Step 4: Display in HUD

Format the cost projection for the HUD/statusline display.

Standard display:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

Format rules:

• All dollar amounts to 2 decimal places
• Projected total prefixed with ~ to indicate estimate
• Use 💰 prefix for the cost line
• Show in a single compact line for statusline integration

When insufficient data (< 2 steps):

💰 Spent: 0.42 USD (need 2+ steps for projection)

Integration: This display line is emitted by the octopus-hud hook and rendered in the statusline alongside phase progress and provider status.

Step 5: Budget Ceiling Warning

If the OCTO_BUDGET_CEILING environment variable is set, compare the projected total against it and warn on overrun.

if [[ -n "${OCTO_BUDGET_CEILING:-}" ]]; then
  ceiling="$OCTO_BUDGET_CEILING"
  if (( $(echo "$projected_total > $ceiling" | bc -l) )); then
    overage=$(echo "$projected_total - $ceiling" | bc -l)
    echo "⚠️ Budget ceiling: ${ceiling} USD — projected to exceed by ${overage} USD"
  fi
fi

Display when over budget:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD

Display when within budget:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
✅ Within budget ceiling: 10.00 USD

Note: OCTO_BUDGET_CEILING is optional. When unset, no ceiling check is performed.

Step 6: Profile Suggestion

If the projected total is high relative to the task, suggest switching to the budget profile to reduce costs.

# Suggest budget profile when projected total exceeds 5.00 USD (configurable)
COST_THRESHOLD="${OCTO_COST_THRESHOLD:-5.00}"
if (( $(echo "$projected_total > $COST_THRESHOLD" | bc -l) )); then
  echo "💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs"
fi

Display:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

The budget profile (OCTO_PROFILE=budget) routes to cheaper models and reduces agent count to minimize spend.

Complete Display Examples

Normal — within budget, moderate cost:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD

Over budget ceiling:

💰 Spent: 2.40 USD | Est. remaining: 3.60 USD | Total: ~6.00 USD
⚠️ Budget ceiling: 5.00 USD — projected to exceed by 1.00 USD
💡 Tip: Switch to OCTO_PROFILE=budget to reduce costs

Early in workflow (insufficient data):

💰 Spent: 0.42 USD (need 2+ steps for projection)

Low cost — no warnings:

💰 Spent: 0.80 USD | Est. remaining: 0.80 USD | Total: ~1.60 USD

Integration

With octopus-hud hook

The cost projection line is rendered as part of the HUD statusline output, updated after each phase completes.

With metrics-tracker.sh

Reads per-phase cost data written by the metrics tracker. Each completed phase logs cost, token counts, and provider details.

With OCTO_PROFILE

When OCTO_PROFILE=budget is active, the projection accounts for reduced per-step costs from cheaper model routing.

Error Handling

No metrics directory:

💰 Cost projection unavailable — no metrics data found

Corrupted metrics data: Skip malformed entries and project from valid data only. If no valid entries remain, show unavailable message.

Zero remaining steps: When all steps are complete, show final total only:

💰 Final cost: 4.80 USD (4 steps)