# Skill Cost Projections

Project remaining workflow cost from per-phase averages, warns on budget ceiling overruns

- Repository: https://github.com/nyldn/claude-octopus (4351 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nyldn/claude-octopus --skill skill-cost-projections -g -a claude-code -y`
Codex: `npx skills add nyldn/claude-octopus --skill skill-cost-projections -g -a codex -y`
Cursor: `npx skills add nyldn/claude-octopus --skill skill-cost-projections -g -a cursor -y`
Gemini CLI: `npx skills add nyldn/claude-octopus --skill skill-cost-projections -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add nyldn/claude-octopus`

## Description

Project remaining workflow cost from per-phase averages, warns on budget ceiling overruns

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

```bash
# 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.

```bash
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.

The rest: https://github.com/nyldn/claude-octopus/blob/HEAD/.claude/skills/skill-cost-projections/SKILL.md